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 has five core entity types. Every reference in the API resolves to one of them:
TypeExamples
person”Lex Fridman”, “Marc Benioff”
organization”OpenAI”, “Anthropic”, “Salesforce”
product”ChatGPT”, “Claude”, “Cursor”
topic”Artificial intelligence”, “Open source models”
channel”TBPN”, “The Iced Coffee Hour”, “Lex Fridman Podcast”
Only person entities have appearances. For every other type, evidence flows through the mention endpoints. Calling an appearance route on a non-person entity returns 400 appearances_person_only. See Appearances vs. mentions.

​
Stable IDs

Every entity is identified by an opaque string of the form: 
ent_123881
The integer suffix is the internal numeric ID. The opaque ent_ prefix is the only thing you should rely on shape-wise. IDs are stable across deploys and surface formatting changes. When two entities are merged (for example, deduping a duplicate “Lex Fridman” record), the canonical ID wins and the merged-away ID continues to resolve. Lookup responses include merged_from_id whenever you hit a non-canonical entry.

​
Resolving names to IDs

If you have a human-readable name, use lookup. It follows merge chains and returns the canonical record:
cURL
curl 'https://api.arcmira.com/v1/entities/lookup?name=OpenAI&type=organization' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
The type parameter is optional but strongly recommended when there’s ambiguity (e.g. “Apple” the company vs. “Apple” the product). You can also look up by ID — useful for sanity checks after caching: 
curl 'https://api.arcmira.com/v1/entities/lookup?id=ent_123881' \
  -H "x-api-key: $ARCMIRA_API_KEY"
Missing entities return 404 entity_not_found. GET /v1/entities/lookup resolves one exact entity. GET /v1/entities/search returns a ranked list — use it for autocomplete UIs, prospecting flows, or anything where the user is still narrowing in. 
curl 'https://api.arcmira.com/v1/entities/search?q=ramp&type=organization&limit=10' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
ParameterDescription
qRequired. Minimum 2 characters. Substring match on canonical entity names; merge-aware.
typeOptional. Filter to person, organization, product, topic, or channel.
has_recommendations_dataOptional. true to restrict to entities with at least one ad_read in brand_profiles.
limit1–25. Default 10. Ordered by appearance_count descending, then name.
Response: 
{
  "data": [
    {
      "id": "ent_14",
      "name": "Ramp",
      "type": "organization",
      "appearance_count": 1200,
      "recommendations_summary": {
        "total_ad_reads": 80,
        "total_endorsements": 12,
        "unique_channels": 45
      }
    }
  ],
  "query": "ramp"
}
  • The recommendations_summary block is included only for callers with Pro+ + recommendations:read. Other callers receive the same row without that field — no error, no 403.
  • Search itself is free (0 rows). Pivot into /v1/recommendations or /v1/mentions for evidence.
  • For exact canonical resolution (e.g. caching ent_* for downstream calls), use /v1/entities/lookup instead — search is fuzzy and may return multiple plausible matches.
/v1/entities/lookup/v1/entities/search
InputExact id or nameFuzzy q (min 2 chars)
OutputOne canonical entityRanked list (up to 25)
Use forStable ID for downstream callsAutocomplete, prospecting
BillingFreeFree

​
Reading entity metadata

The direct read returns canonical metadata in the same shape as lookup: 
curl 'https://api.arcmira.com/v1/entities/ent_123881' \
  -H "x-api-key: $ARCMIRA_API_KEY"
Response (truncated)
{
  "entity": {
    "id": "ent_123881",
    "canonical_id": "ent_123881",
    "name": "OpenAI",
    "type": "organization",
    "platform": null,
    "url": "https://openai.com",
    "image_url": "https://cdn.arcmira.com/...",
    "appearance_count": 0,
    "is_canonical": true,
    "merged_from_id": null,
    "route": "/organizations/openai"
  }
}
For non-person entities, appearance_count is always 0 and route is the web-app surface for the type.

​
Commercial summary (Pro+)

On organization and product entities, Pro+ callers with recommendations:read also receive a recommendations_summary block: 
{
  "entity": { "id": "ent_14", "name": "Ramp", "type": "organization" },
  "recommendations_summary": {
    "total_ad_reads": 80,
    "total_endorsements": 12,
    "unique_shows": 38,
    "first_seen_at": "2025-02-01",
    "last_seen_at": "2026-04-24",
    "channels_as_sponsor": 12
  }
}
  • channels_as_sponsor is the number of distinct channels where this entity is registered as a known advertiser.
  • total_ad_reads, total_endorsements, unique_shows, and first_seen_at / last_seen_at come from brand_profiles aggregations.
  • The block is omitted when the entity has no commercial signal. Persons, topics, and channels never receive it.
  • The summary costs zero rows.
For the underlying rows, pivot to /v1/entities/{id}/recommendations.

​
Channel page teaser

GET /v1/channels/{slug} includes a recommendations_summary teaser: 
{
  "recommendations_summary": {
    "sponsor_count": 40,
    "top_sponsors": ["Ramp", "Public", "Bezel"]
  }
}
  • sponsor_count is visible to every caller, regardless of tier or scope — it’s a discoverability signal so non-Pro+ integrators know that commercial data exists for the channel.
  • top_sponsors only appears for Pro+ callers with recommendations:read.
The full sponsor list lives at /v1/channels/{id}/sponsors. For deep dives, every entity exposes related lists. They use the same limit/cursor pagination as everything else: 
GET /v1/people/{slug}/topics
GET /v1/people/{slug}/people
GET /v1/people/{slug}/organizations
GET /v1/people/{slug}/products
GET /v1/people/{slug}/channels
The same set exists under /v1/topics/{slug}/..., /v1/organizations/{slug}/..., /v1/products/{slug}/..., and /v1/channels/{slug}/.... Channels also expose /v1/channels/{slug}/guests. See the API reference for the full schema.