Search - Arcmira API

Just want working code?

Stop reading and copy the Search coding agent reference into your agent. It is self-contained.

Search is the one-shot half of Arcmira: ask the index a question, get evidence back. Resolve any person, organization, product, topic, or channel to a stable ID, then pull every mention of it across long-form video and podcasts, with timestamps, sentiment, and context quotes. If the same interest should fire again as new media lands, use Monitors. If you already have a video and need its full text, use Transcripts.

Key capabilities

Capability	What it does
Entity resolution	Names to stable `ent_*` IDs, merge-aware, across five entity types
Discovery search	Ranked fuzzy search for autocomplete and prospecting
Mentions	Evidence rows tying an entity to media, with seconds-level timestamps and sentiment
Appearances	The stricter person-only subset: the person was actually present
Related entities	Who and what co-occurs with an entity: people, topics, orgs, products, channels
Commercial intelligence	Ad reads, endorsements, and sponsor rollups (Pro+); see Commercial intelligence

The entity model

Every reference in the API resolves to one of five types: person, organization, product, topic, channel. Tracking is entity-level, not keyword-level: “Apple” the company and “apple” the fruit don’t collide, and a topic like “weather modification” is tracked as a concept.

Stable IDs. Entities are identified by opaque strings like ent_123881. When duplicates merge, the canonical ID wins and merged-away IDs keep resolving; lookup responses carry merged_from_id when you hit an alias.
Only people have appearances. An appearance means a person was actually present in the media (interview, panel, hosting). Everything else is a mention: the entity was referenced. Calling an appearance surface for a non-person returns 400 appearances_person_only, and is_appearance=true on mentions is person-only too.

Common use cases

Map the universe talking about a brand

Resolve once, then page through every mention filtered by sentiment, date, or channel.

const lookup = await fetch(
  'https://api.arcmira.com/v1/entities/lookup?name=Ramp&type=organization',
  { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
).then(r => r.json());

const mentions = await fetch(
  `https://api.arcmira.com/v1/mentions?entity_id=${lookup.entity.id}&sentiment=positive&limit=50`,
  { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
).then(r => r.json());

Vet a guest before booking them

Pull a person’s actual appearances (not name-drops), then their related topics to see what they talk about.

curl 'https://api.arcmira.com/v1/people/lex-fridman/appearances?limit=10' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
curl 'https://api.arcmira.com/v1/people/lex-fridman/topics?limit=10' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Find every discussion of a niche topic this quarter

Topics are entities. Filter mentions by date window and free text.

curl 'https://api.arcmira.com/v1/mentions?entity_name=weather%20modification&entity_type=topic&date_from=2026-04-01&limit=50' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Check a company's commercial footprint

Discovery search can filter to entities with commercial data; the depth lives in Commercial intelligence (Pro+).

curl 'https://api.arcmira.com/v1/entities/search?q=ramp&type=organization&has_recommendations_data=true' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Then pivot to Commercial intelligence for ad reads, endorsements, and sponsor rollups.

Quickstart

Resolve the entity

curl 'https://api.arcmira.com/v1/entities/lookup?name=OpenAI&type=organization' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Cache the returned entity.id (ent_123881). Pass type whenever names are ambiguous.

Pull evidence

curl 'https://api.arcmira.com/v1/entities/ent_123881/mentions?sentiment=negative&limit=25' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Each row carries start_seconds/end_seconds (integer seconds; 0 means the full episode), sentiment_score in [-1, 1], a bucketed sentiment label, confidence, and a context quote. The legacy start_timestamp/end_timestamp MM:SS strings are still present but deprecated.

Paginate

Responses return { data, has_more, next_cursor }. Pass next_cursor back as cursor until has_more is false. See Requests & conventions.

Choosing well

Discover vs pin. Three lookup surfaces, three jobs:

Surface	Job	Returns
`GET /v1/search`	Resolve a free-text name to the single best match	One entity (`{ found: ... }`), or `found: false`
`GET /v1/entities/search`	Entity discovery with filters (`type`, `has_recommendations_data`)	Ranked list, up to 25
`GET /v1/entities/lookup`	Pin one canonical `ent_*` for production use	One entity, merge-resolved

Rule: resolve with lookup and cache the ID before any metered pull. Pulling mentions by entity_name works, but embeds a resolution in every request and breaks silently if the name is ambiguous. All three lookup surfaces are free. Evidence class. Pick the row population before you pull:

Class	Endpoint	Timestamps	Cost	Gate
Mentions	`/v1/mentions`, `/v1/entities/{id}/mentions`	`start_seconds`/`end_seconds`	1 row each	`read`
Appearances	`/v1/mentions?is_appearance=true` (or `/v1/people/{slug}/appearances`, single-page)	`start_seconds`/`end_seconds`	1 row each	`read`, person-only
Commercial	`/v1/recommendations`, `/v1/channels/{id}/sponsors`	`start_seconds`/`end_seconds`	10 rows each	Pro+ + `recommendations:read`

Enrichment tradeoff. details=full on mentions attaches matching commercial rows to each mention: one call instead of two, but it charges the mention row plus 10 rows for every attached commercial item. Omit it unless you need the commercial overlay on that specific pull. Row budgeting. Search, lookup, and discovery are free; the rows you then fetch are not. Use date_from/date_to to scope pulls, pull larger pages (up to limit=100) when iterating, and check /v1/me → usage.rows_remaining before large jobs. See Usage, limits & billing.

Constraints

All read endpoints need only the read scope. Commercial surfaces need a Pro+ tier and recommendations:read; check /v1/me → recommendations_api_enabled before calling.
Appearances are person-only, enforced with 400 appearances_person_only.
Mention and commercial rows carry timestamps twice: read the numeric start_seconds/end_seconds (integer seconds; 0 means the full episode, no specific moment). The MM:SS (or HH:MM:SS) string fields are deprecated and will be removed after a changelog-announced sunset.
Entity resolution is merge-aware: a query against a canonical ID covers its full merge chain.

Community Review

Any Search result your key can read, it can dispute, for free. Submit the reproducing query and corrections targeting the row’s public ID (ent_*, men_*, com_*) to POST /v1/feedback:

curl -X POST 'https://api.arcmira.com/v1/feedback?type=mentions' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": { "entity_name": "Mercury", "entity_type": "organization" },
    "corrections": [{
      "id": "men_2049815",
      "issue_type": "wrong_entity",
      "notes": "These rows look like the planet, not the bank."
    }]
  }'

Nothing auto-applies; reviewers triage every submission. Full type catalog, issue codes, and shapes: Community Review.

Search for coding agents: every endpoint, parameter, and known mistake on one page.
Commercial intelligence: the paid evidence layer (Pro+).
Monitors: turn a Search interest into standing alerts.
API reference: interactive playground per endpoint.

​Key capabilities

​The entity model

​Common use cases

​Quickstart

​Choosing well

​Constraints

​Community Review

​Next