Skip to main content

Overview

Search resolves entities and pulls evidence from Arcmira’s media index (long-form video and podcasts on YouTube).
  • Base URL: https://api.arcmira.com, all paths under /v1.
  • Auth: Authorization: Bearer arc_sk_... or x-api-key: arc_sk_.... If both are sent, x-api-key wins.
  • Scope: all endpoints on this page need read (present on every key). Commercial endpoints additionally need a Pro+ tier AND the recommendations:read scope; verify with GET /v1/merecommendations_api_enabled and scopes.
  • Billing: lookups and searches are free. Mention/appearance rows cost 1 row each from the shared monthly pool (the first 5 rows of each distinct pull are free). Commercial rows bill at 10 rows each. GET /v1/me costs 0 rows; check usage.rows_remaining before large pulls.
  • Five entity types: person, organization, product, topic, channel. Only person has appearances.

Minimal working example

Endpoints

GET /v1/entities/lookup: resolve to a canonical ID

Exact resolution. Pass name (+ optional type) or id. Follows merge chains; response is { "entity": { id, name, type, merged_from_id, route, ... } }. merged_from_id is non-null when the input was an alias. Free. Missing entities: 404 entity_not_found.

GET /v1/entities/search: ranked discovery

Fuzzy, ranked, free. q (required, min 2 chars), type, has_recommendations_data=true, limit (1-25, default 10). Single page, no cursor. Ordered by appearance_count desc. Rows include recommendations_summary only for Pro+ callers with recommendations:read; other callers get the same row without that field (no error).

GET /v1/search: resolve a name to a single entity

Single-result name resolution for a free-text q (+ optional type). Returns the best match as { found: true, ... } or { found: false }. The entity.id here is a raw number; prefix it as ent_{id} for the entities endpoints, or use lookup, which returns the public form. Single result, no pagination. Free. Use entities/search for ranked lists; use lookup when you already know the exact name or ID.

GET /v1/entities/: read canonical metadata

{ "entity": { id, canonical_id, name, type, url, image_url, appearance_count, is_canonical, merged_from_id, route } }. On organization/product entities, Pro+ + recommendations:read callers also get a recommendations_summary aggregate block (0 rows). appearance_count counts indexed mention/appearance rows for any entity type.

GET /v1/entities/cards: batched compact cards

ids as a comma-separated list of raw integer entity IDs (ids=12,844,1032, 1-50 of them); the ent_* form is not accepted here. Returns compact card objects under the requested IDs; unknown IDs are silently dropped. Free.

GET /v1/mentions: evidence rows

The primary evidence surface. At least one of entity_id or entity_name is required; if both are sent, entity_id wins.

GET /v1/entities//mentions: entity-scoped variant

Identical shape and filters (minus entity_*); the entity rides in the path. Preferred for production: explicit, no URL-encoded names.

GET /v1/people//appearances: person appearances

The appearance subset for one person. Person-only: the equivalent route for any other type returns 400 appearances_person_only. Documented exception: this route and the related-entity lists below return { items, total, offset, limit, hasMore } (camelCase, offset-based, with a total) instead of the standard { data, has_more, next_cursor } envelope. No cursor is returned, so pages past the first are not reachable here today. For appearance rows with standard pagination, date filters, and the mention-row shape, prefer GET /v1/mentions?entity_id=...&is_appearance=true.
Filters: q (substring), field, sort, order. One row each. Same { items, total, ... } exception shape as appearances above; raise limit (max 100) and narrow with q instead of paging.

Commercial endpoints (Pro+ + recommendations:read)

Key params: mention_class (ad_read|endorsement|mention|all, default all), min_confidence (default 0.7), include_disputed (default false), min_ad_reads (sponsors, default 3), status (sponsors: active|lapsed|ended|uncertain). Full narrative: Commercial intelligence.

Response schema

Mention row (the shape you will parse most):
With details=full, each row gains recommendations: { items: [...] } where items carry com_* IDs, mention_class, verbatim_quote, promo_code, and timestamps (start_seconds/end_seconds plus the deprecated MM:SS strings); items is [] when nothing matches.

Errors

Envelope on every error:
Switch on error.code, never on error.message. Quote X-Request-Id to support.

Rate limits & idempotency

  • Per-key fixed 60-second window: free 60/min, paid (incl. Ultra) 240, teams/enterprise 600. Headers on every authenticated response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; 429s add Retry-After.
  • Every data endpoint on this page is GET: no Idempotency-Key needed, retries are safe. The one write is POST /v1/feedback below; send Idempotency-Key on it.

Community Review

Every result on this page is disputable, free (0 rows), via POST /v1/feedback. Pick the type matching the surface you called, echo the reproducing query, and target rows by public ID: Check any submission’s status later with GET /v1/feedback/{feedback_id}.
Nothing auto-applies. Supports Idempotency-Key. Up to 100 corrections per submission. Full catalog: Community Review.

Common mistakes

Wrong parameters and patterns frequently generated for this API. Do not use the left column.

Patterns and gotchas

  • Resolve-then-pull: lookups are free, metered rows are not; never burn rows on an ambiguous name.
  • recommendations_summary blocks are aggregates and cost 0 rows; row-level pulls are what bill.
  • details=full multiplies cost (mention rows + 10 rows per attached commercial item); use only when you need the overlay.
  • Merge-aware queries: querying a canonical ent_* includes rows from entities merged into it. If results look split across variants, that is a merge_suggestion for Community Review, not a client-side join.
  • has_more: false means next_cursor: null; stop paging.
  • Watch RateLimit-Remaining while iterating; back off before hitting 429.
  • Every response carries X-Request-Id; log it.

Complete examples

Full evidence pull with pagination and budget check: