Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt

Use this file to discover all available pages before exploring further.

Arcmira’s index distinguishes between an entity being mentioned in media and an entity appearing in media. The rule:
  • A mention is any row that links any entity to a piece of media.
  • An appearance is the stricter case where a person is actually present (interview, talk, panel, hosting, etc.) — not just referenced.
Because “appearance” only makes sense for people, the API gates the concept at the type level.

​
The rule

Entity typeAppearances?Mentions?
personyesyes
organizationnoyes
productnoyes
topicnoyes
channelnoyes

​
How the API enforces it

​
Appearance routes are person-only

Only /v1/people/{slug}/appearances exists. The non-person variants explicitly reject: 
curl 'https://api.arcmira.com/v1/organizations/OpenAI/appearances' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

{
  "error": {
    "type": "invalid_request_error",
    "code": "appearances_person_only",
    "message": "Only person entities can have appearances. Organizations, products, topics, and channels are exposed as mentions; use /v1/mentions or /v1/entities/{id}/mentions instead.",
    "doc_url": "https://docs.arcmira.com/errors#appearances_person_only",
    "request_id": "req_..."
  }
}
The OpenAPI document hides those non-person appearance paths so generated clients and the API reference never tempt you to call them.

​
is_appearance=true is person-only on mentions

The mentions endpoints accept is_appearance as a filter, but it only means something for people: 
curl 'https://api.arcmira.com/v1/mentions?entity_name=OpenAI&entity_type=organization&is_appearance=true&limit=1' \
  -H "x-api-key: $ARCMIRA_API_KEY"
returns 400 appearances_person_only. For non-person entities, omit is_appearance or pass false and the request succeeds. The returned rows always have "is_appearance": false.

​
What to use instead

  • For organizations / products / topics / channels: GET /v1/mentions?entity_id=... or GET /v1/entities/{id}/mentions. Filter with q, sentiment, channel_id, etc.
  • For people: both work. Use /v1/people/{slug}/appearances when you specifically want the appearance subset, and the mention endpoints when you want all references.

​
Why this distinction matters

It keeps two product surfaces honest:
  1. The web app’s “appearance” feed on person pages is verifiable evidence that a person was actually on a piece of media — not just name-dropped.
  2. Anything that runs over orgs, products, topics, or channels uses mentions semantics consistently, so sentiment, channel filters, and counts compose cleanly across types.
Following the same split in your integration code prevents the corresponding bug — surfacing an “appearance” count for a non-person and confusing your users.