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

# Quickstart

Arcmira is an SF-based AI company and the search engine for the spoken web.

The API indexes long-form video and podcasts on YouTube, extracts who and what is discussed (with sentiment and timestamps), and exposes it as three capabilities:

<CardGroup cols={3}>
  <Card title="Search" icon="search" href="/search">
    One-shot answers from the index: pull entity mentions, appearances, and commercial evidence.
  </Card>

  <Card title="Monitors" icon="bell" href="/monitors">
    Standing interests that fire again as new media lands. Alerts delivered to email, Slack, and webhooks.
  </Card>

  <Card title="Transcripts" icon="scan-text" href="/transcripts">
    Fully analyzed transcripts: read, generate on demand, and submit corrections.
  </Card>
</CardGroup>

Use **Search** for one-shot answers. Use **Monitors** when that interest should fire again as new media lands. Use **Transcripts** when you have a video and need the fully analyzed text. Use [**Community Review**](/feedback) whenever any result looks wrong.

<Note>
  **Using a coding agent?** Each capability has a self-contained reference built for agents: [Search](/search-for-coding-agents), [Monitors](/monitors-for-coding-agents), [Transcripts](/transcripts-for-coding-agents). Copy the one you need into your agent and it has everything: endpoints, schemas, errors, and known mistakes.
</Note>

The API is HTTP/JSON at `https://api.arcmira.com`, versioned under `/v1`. API calls draw from the same monthly **row pool** as web usage on your plan; there is no separate API tier. There is no SDK yet: the examples below use plain `fetch` and `httpx`, and everything works from any HTTP client.

## 1. Create a key

Sign in at [arcmira.com](https://arcmira.com), open [Dashboard → API Keys](https://arcmira.com/dashboard?tab=api-keys), and click **Create key**.

You will see the key exactly once. It looks like:

```text theme={null}
arc_sk_a1b2c3d4e5f6...
```

Store it in your secrets manager and export it as `ARCMIRA_API_KEY`. Treat it like a password: never ship it in browser code.

<Tip>
  Need write access for monitors or trackers? Tick **Manage monitors** or **Manage trackers** when creating the key. All keys include `read`. On Pro+ plans, `recommendations:read` unlocks [Commercial intelligence](/commercial-intelligence). See [Authentication & scopes](/authentication).
</Tip>

## 2. Search for an entity

<CodeGroup>
  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://api.arcmira.com/v1/search?q=lex%20fridman',
    { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
  );
  const json = await res.json();
  console.log(res.headers.get('X-Request-Id'), json);
  ```

  ```python Python theme={null}
  import os, httpx

  r = httpx.get(
      'https://api.arcmira.com/v1/search',
      params={'q': 'lex fridman'},
      headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"},
  )
  r.raise_for_status()
  print(r.headers['X-Request-Id'], r.json())
  ```

  ```bash cURL theme={null}
  curl 'https://api.arcmira.com/v1/search?q=lex%20fridman' \
    -H "Authorization: Bearer $ARCMIRA_API_KEY"
  ```
</CodeGroup>

The response resolves your text to the single best entity match (`{ found: true, ... }`), with type, route, and basic stats. For ranked lists use `/v1/entities/search`. Note the `X-Request-Id` header: include it whenever you contact support.

## 3. Resolve to a canonical ID

Search is a discovery tool. Production integrations pin a canonical `ent_<id>` and cache it:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://api.arcmira.com/v1/entities/lookup?name=OpenAI&type=organization',
    { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
  );
  const { entity } = await res.json();
  // entity.id -> "ent_123881"; entity.merged_from_id set when you hit an alias
  ```

  ```python Python theme={null}
  import os, httpx

  r = httpx.get(
      'https://api.arcmira.com/v1/entities/lookup',
      params={'name': 'OpenAI', 'type': 'organization'},
      headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"},
  )
  entity = r.json()['entity']  # entity['id'] -> "ent_123881"
  ```

  ```bash cURL theme={null}
  curl 'https://api.arcmira.com/v1/entities/lookup?name=OpenAI&type=organization' \
    -H "Authorization: Bearer $ARCMIRA_API_KEY"
  ```
</CodeGroup>

Lookup follows merge chains: old IDs keep resolving, and `merged_from_id` tells you when they did.

## 4. Pull evidence

Mentions are the evidence layer. Each row links one entity to one piece of media with timestamps, sentiment, and a context quote:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://api.arcmira.com/v1/mentions?entity_id=ent_123881&sentiment=positive&limit=25',
    { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
  );
  const { data, has_more, next_cursor } = await res.json();
  ```

  ```python Python theme={null}
  import os, httpx

  r = httpx.get(
      'https://api.arcmira.com/v1/mentions',
      params={'entity_id': 'ent_123881', 'sentiment': 'positive', 'limit': 25},
      headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"},
  )
  body = r.json()  # body['data'], body['has_more'], body['next_cursor']
  ```

  ```bash cURL theme={null}
  curl 'https://api.arcmira.com/v1/mentions?entity_id=ent_123881&sentiment=positive&limit=25' \
    -H "Authorization: Bearer $ARCMIRA_API_KEY"
  ```
</CodeGroup>

## 5. Keep tracking it

When a one-time lookup should become an ongoing interest, create a tracker (requires `trackers:write`):

<CodeGroup>
  ```typescript TypeScript theme={null}
  const res = await fetch('https://api.arcmira.com/v1/trackers', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}`,
      'Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ entityName: 'OpenAI', entityType: 'organization' }),
  });
  ```

  ```python Python theme={null}
  import os, uuid, httpx

  r = httpx.post(
      'https://api.arcmira.com/v1/trackers',
      json={'entityName': 'OpenAI', 'entityType': 'organization'},
      headers={
          'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}",
          'Idempotency-Key': str(uuid.uuid4()),
      },
  )
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.arcmira.com/v1/trackers' \
    -H "Authorization: Bearer $ARCMIRA_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{ "entityName": "OpenAI", "entityType": "organization" }'
  ```
</CodeGroup>

From here, [Monitors](/monitors) group trackers and deliver alerts to email, Slack, or an HMAC-signed webhook.

## Next

* [Search](/search): entities, mentions, appearances, and how to choose between them.
* [Monitors](/monitors): the full tracking lifecycle, delivery channels, and alert history.
* [Transcripts](/transcripts): read, unlock, generate, and correct full transcripts.
* [Commercial intelligence](/commercial-intelligence): ad reads, endorsements, and channel sponsors (Pro+).
* [Community Review](/feedback): fix anything that looks wrong, on any surface, for free.
* [Errors](/errors) and [Usage, limits & billing](/usage-and-billing): what to expect operationally.