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.

Mentions are the evidence layer behind Arcmira. Each row links one entity to one piece of media with timestamps, surrounding context, sentiment, and source-channel metadata. 
GET /v1/mentions
GET /v1/entities/{id}/mentions
The first form takes the entity as a filter; the second pins it in the path. They return the same shape and accept the same filters (minus entity_*).
Only person entities can have appearances. For organizations, products, topics, and channels, rows are always mentions. Passing is_appearance=true for a non-person entity returns 400 appearances_person_only. See Appearances vs. mentions.

​
Minimal request

cURL
curl 'https://api.arcmira.com/v1/mentions?entity_id=ent_123881&limit=25' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
Node 20+
const res = await fetch(
  'https://api.arcmira.com/v1/mentions?entity_id=ent_123881&limit=25',
  { headers: { 'x-api-key': process.env.ARCMIRA_API_KEY } },
);
const { data, has_more, next_cursor, entity } = await res.json();
You can target by ID or name — exactly one of entity_id or entity_name is required.
By name
curl 'https://api.arcmira.com/v1/mentions?entity_name=OpenAI&entity_type=organization&limit=10' \
  -H "x-api-key: $ARCMIRA_API_KEY"
entity_type is optional but strongly recommended when names are ambiguous.

​
Filters

ParameterDescription
entity_idCanonical ent_<id>. Mutually exclusive with entity_name.
entity_nameHuman-readable name. Pair with entity_type to disambiguate.
entity_typeOne of person, organization, product, topic, channel.
channel_idRestrict to a single channel (YouTube channel ID).
channel_nameSubstring match on the source channel name.
qFree-text search over mention description, media title, entity name, channel name.
sentimentOne of positive, neutral, negative (uses the same thresholds as the web app).
is_appearancetrue or false. Person entities only.
date_fromISO date. Lower bound (inclusive) on published_at.
date_toISO date. Upper bound (inclusive) on published_at.
details"full". Attaches matching commercial recommendations to each row. Pro+ + recommendations:read.
limit1–100. Default 20.
cursorOpaque cursor from a previous response’s next_cursor.

​
Response shape

{
  "data": [
    {
      "id": "men_2049815",
      "appearance_id": 2049815,
      "entity": {
        "id": "ent_123881",
        "name": "OpenAI",
        "type": "organization"
      },
      "media": {
        "id": 9912345,
        "video_id": "abcd_1234",
        "title": "...",
        "url": "https://www.youtube.com/watch?v=abcd_1234",
        "published_at": "2026-04-12T14:00:00Z",
        "channel_id": "UCabc...",
        "view_count": 412034,
        "source_channel": {
          "id": "ent_5012",
          "name": "TBPN",
          "url": "https://www.youtube.com/@tbpn"
        }
      },
      "start_timestamp": 412,
      "end_timestamp": 478,
      "is_appearance": false,
      "description": "OpenAI's new model release...",
      "confidence": 0.93,
      "sentiment_score": 0.42,
      "sentiment": "positive",
      "referenced_url": null,
      "referenced_platform": null,
      "extracted_content": "..."
    }
  ],
  "has_more": true,
  "next_cursor": "eyJvZmZzZXQiOjI1fQ",
  "entity": {
    "id": "ent_123881",
    "name": "OpenAI",
    "type": "organization",
    "appearance_count": 0
  }
}
A few notes:
  • is_appearance is always false for non-person entities, regardless of the underlying row.
  • sentiment is the bucketed label; sentiment_score is the raw [-1, 1] score.
  • start_timestamp / end_timestamp are seconds into the source media when available.
  • source_channel is null for non-YouTube media.

​
Pagination

Mentions paginate via cursors. Pass the previous response’s next_cursor as the cursor query parameter. has_more tells you whether to keep going. See Pagination for the full pattern.

​
Enrichment with details=full

Pro+ callers with recommendations:read can attach matching commercial recommendations to every mention row by adding details=full. The rest of the response shape is unchanged. 
curl 'https://api.arcmira.com/v1/mentions?entity_id=ent_14&details=full&limit=10' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
Each row gains a recommendations block listing any commercial-pipeline rows that share the same (entity, media) pair: 
{
  "id": "men_2049815",
  "appearance_id": 2049815,
  "entity": { "id": "ent_14", "name": "Ramp", "type": "organization" },
  "media": { "id": 9912345, "video_id": "...", "title": "..." },
  "recommendations": {
    "items": [
      {
        "id": "com_119682",
        "mention_class": "ad_read",
        "verbatim_quote": "...",
        "promo_code": "RAMP20",
        "offer": null,
        "confidence": 0.95,
        "start_timestamp": "12:34",
        "end_timestamp": "13:02"
      }
    ]
  }
}
Notes:
  • recommendations.items is [] for rows with no matching commercial extraction. The block is always present when details=full.
  • Items reuse the public com_* ID scheme — use them with POST /v1/feedback to correct individual rows.
  • Disputed recommendations are excluded; there is no include_disputed knob on the mentions endpoint.
  • Without details=full, the response is identical to v1.0.0 — no new fields, no breaking changes.
Lower tiers receive 403 recommendations_not_enabled when details=full is requested. Pro+ keys missing recommendations:read receive 403 insufficient_scope. See Commercial intelligence for the gate details. details=full charges one row per mention plus the premium row rate for each commercial enrichment item. See Usage & billing.

​
Entity-scoped variant

If you already have an ent_<id>, the entity-scoped path is identical except for how you express the target: 
curl 'https://api.arcmira.com/v1/entities/ent_123881/mentions?sentiment=positive&limit=10' \
  -H "x-api-key: $ARCMIRA_API_KEY"
This is the recommended shape for production integrations — it makes the entity explicit, doesn’t require URL-encoding names, and keeps logs cleaner.