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.

Alongside its appearance index, Arcmira runs a second extraction pipeline that classifies on-camera commercial activity: paid ad reads, organic endorsements, and the recurring sponsor relationships behind them. That data is exposed through a separate commercial intelligence API surface, available on Pro+ plans.
Commercial intelligence is gated behind the Pro+ tier (pro_plus, ultra, teams, enterprise) and the recommendations:read scope. Callers on lower tiers get 403 recommendations_not_enabled. See Scopes and Usage & billing.

​
The two universes

Arcmira’s index has two independent extraction pipelines. Understanding the split keeps your integration honest.
UniverseSource tableEndpointWhat it answers
Mentionsappearances/v1/mentions, /v1/entities/{id}/mentions”Where was this entity talked about?”
Recommendationsrecommendations/v1/recommendations, /v1/entities/{id}/recommendations”Where was this entity paid for or endorsed?”
The pipelines use different prompts, different quality rules, and different false-positive profiles. They are deliberately not joined into a single result set — the /v1/mentions?details=full variant attaches matching recommendations to each appearance row, but the two row populations remain distinct.

​
Which surface should I call?

Pulling brand evidence

Use /v1/mentions. Returns every reference to an entity — paid, organic, or incidental.

Tracking ad spend & sponsors

Use /v1/recommendations. Returns only rows the extraction pipeline classified as ad_read, endorsement, or mention inside the commercial pipeline.

Channel advertiser lists

Use /v1/channels/{id}/sponsors. Recurring sponsor rollup with sponsor status and ad-read counts.

Closing the loop on quality

Use POST /v1/feedback. Submit corrections against the exact query you ran; Arcmira re-aggregates the affected entities.

​
Classification

Every row in the recommendations universe has a mention_class:
ClassDefinition
ad_readA paid sponsor read. Typically explicit (“this episode is brought to you by…”), often with a promo code.
endorsementAn organic recommendation from a host or guest. No money involved; the speaker vouches for the product.
mentionA low-signal commercial reference that didn’t meet the ad_read / endorsement bar. Surfaced for context.
Filter with mention_class=ad_read|endorsement|mention|all on /v1/recommendations. The default is all.

​
Quality rules baked in

The recommendations pipeline runs additional cleanup beyond raw extraction:
  • Recurring sponsor threshold. Entities with fewer than 3 ad_read rows on a channel are treated as one-offs, not sponsors. Tunable via min_ad_reads on the channel sponsors endpoint.
  • Singleton reclassification. A single ad_read for an entity that isn’t a known advertiser and has no sponsor language in the quote is downgraded to mention.
  • Entity merges. Canonical resolution flows through entities.merged_into_entity_id, so Bazel resolves to Bezel, Julius to Julius AI, etc. — your query against a canonical ent_* covers the full merge chain.
  • Conflict handling. Rows with conflict_status = 'disputed' are excluded by default. Pass include_disputed=true on /v1/recommendations to see them.

​
IDs you’ll see

ResourcePrefixExample
Entityent_ent_14
Appearance mentionmen_men_2049815
Commercial recommendationcom_com_119682
com_* IDs are what you pass to POST /v1/feedback when correcting a single row.

​
Tier and scope check

Before you call any commercial route, confirm both gates: 
curl https://api.arcmira.com/v1/me \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

{
  "user_id": "usr_...",
  "tier": "pro_plus",
  "scopes": ["read", "recommendations:read"],
  "rate_limit": 240,
  "recommendations_api_enabled": true,
  "usage": { "rows_used": 1234, "rows_remaining": 98766, "monthly_rows": 100000, "current_spend_cents": 0 }
}
  • recommendations_api_enabled is true only on Pro+ tiers.
  • recommendations:read enables reads; recommendations:write enables POST /v1/feedback. Both are toggled on individual keys in Settings → API Keys.
If recommendations_api_enabled is false, upgrade the plan — the scope checkbox is hidden until you do.

​
What next

Recommendations

Filters, response shape, and the mention_class model.

Channel sponsors

Recurring advertisers on a YouTube channel, with sponsor status.

Feedback

Submit corrections against any commercial query.

Mentions enrichment

Attach commercial recommendations to mention rows with details=full.