> ## 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.

> ## Agent Instructions
> Arcmira has three API capabilities: Search (entities, mentions, appearances, commercial intelligence), Monitors (trackers plus alert delivery), and Transcripts (read, generate, correct). Community Review is the cross-surface correction layer.
> Discover pages at https://docs.arcmira.com/llms.txt, then fetch the matching page's .md export. Each capability has a self-contained '<capability> for coding agents' page; prefer it.
> Auth: Authorization: Bearer arc_sk_... or x-api-key: arc_sk_... (x-api-key wins if both are sent). Never put keys in browser code. Check GET /v1/me for tier, scopes, and remaining rows before metered pulls.
> Search: resolve names with GET /v1/entities/lookup and pin ent_* IDs before pulling metered rows. Only person entities have appearances. Mention and recommendation rows carry canonical numeric timestamps in start_seconds/end_seconds (integer seconds; 0 means full episode); the MM:SS string fields are deprecated. Commercial routes need Pro+ tier AND the recommendations:read scope and bill 10 rows per row.
> Monitors: a tracker watches one entity; a monitor groups trackers with shared delivery (email, Slack, HMAC-signed webhooks). Create trackers with POST /v1/trackers, then attach by id: POST /v1/monitors/{id}/trackers { trackerIds: [...] }. Each fired alert occurrence debits 100 rows. Poll GET /v1/monitors/{id}/alerts?n= for recent deliveries. Send Idempotency-Key on every POST/PATCH.
> Transcripts: switch on the access field (unlocked, locked, premium_pending, not_transcribed, unauthenticated). Honor Retry-After when polling POST /v1/transcriptions jobs. Corrections (POST /v1/videos/{video_id}/corrections; kinds line_edit, speaker_reassign, speaker_identify, add_person, entity_tag, segment_rewrite) cost 0 rows; anchored kinds need revision + anchor.contentHash (djb2 base-36); handle 409 (re-anchor) and 412 (expectedSeq). segment_rewrite replaces an inclusive segment range with new segments (empty replacements array deletes; timestamps repaired server-side).
> Community Review is free (0 rows) and surface-typed: POST /v1/feedback with a type matching the surface you called, the reproducing query, and corrections targeting public IDs (ent_*, men_*, com_*). Nothing auto-applies. Do not send untyped notes.
> Errors: switch on error.code, follow doc_url, quote X-Request-Id to support. Honor Retry-After on 429. Retries of POST/PATCH must reuse the same Idempotency-Key; replays return Idempotency-Replayed: true.

# Search

> Resolve entities and pull evidence from the index: mentions, appearances, related entities, and commercial signals.

<div className="callout-box not-prose">
  <p className="callout-title">Just want working code?</p>

  <p className="callout-body">
    Stop reading and copy the [Search coding agent reference](/search-for-coding-agents) into your agent. It is self-contained.
  </p>
</div>

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](/monitors). If you already have a video and need its full text, use [Transcripts](/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](/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

<AccordionGroup>
  <Accordion title="Map the universe talking about a brand">
    Resolve once, then page through every mention filtered by sentiment, date, or channel.

    ```typescript theme={null}
    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());
    ```
  </Accordion>

  <Accordion title="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.

    ```bash theme={null}
    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"
    ```
  </Accordion>

  <Accordion title="Find every discussion of a niche topic this quarter">
    Topics are entities. Filter mentions by date window and free text.

    ```bash theme={null}
    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"
    ```
  </Accordion>

  <Accordion title="Check a company's commercial footprint">
    Discovery search can filter to entities with commercial data; the depth lives in Commercial intelligence (Pro+).

    ```bash theme={null}
    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](/commercial-intelligence) for ad reads, endorsements, and sponsor rollups.
  </Accordion>
</AccordionGroup>

## Quickstart

<Steps>
  <Step title="Resolve the entity">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Pull evidence">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Paginate">
    Responses return `{ data, has_more, next_cursor }`. Pass `next_cursor` back as `cursor` until `has_more` is `false`. See [Requests & conventions](/requests).
  </Step>
</Steps>

## 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](/usage-and-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`:

```bash theme={null}
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](/feedback).

## Next

* [Search for coding agents](/search-for-coding-agents): every endpoint, parameter, and known mistake on one page.
* [Commercial intelligence](/commercial-intelligence): the paid evidence layer (Pro+).
* [Monitors](/monitors): turn a Search interest into standing alerts.
* [API reference](/api-reference/entities/resolve-an-entity-to-its-canonical-stable-id): interactive playground per endpoint.