> ## 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 ' 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. # Authentication & scopes > API key headers, key hygiene, and the scope matrix that gates read and write access. Every Arcmira v1 endpoint except `/v1/health` and `/v1/openapi.json` requires authentication. Pass your key in either of two equivalent headers: ```bash Bearer token (preferred) theme={null} Authorization: Bearer arc_sk_your_key ``` ```bash API key header theme={null} x-api-key: arc_sk_your_key ``` The two forms are interchangeable. If both headers are sent, `x-api-key` wins. ## Key format Arcmira keys start with the `arc_sk_` prefix and contain 64 hex characters after it. The dashboard only displays the prefix and last 4 characters after creation. The raw secret is shown **once**, at creation time. ```text theme={null} arc_sk_a1b2c3d4...xxxx ``` ## Creating keys 1. Go to [Dashboard → API Keys](https://arcmira.com/dashboard?tab=api-keys). 2. Click **Create key**, give it a descriptive name (e.g. `production-backend`), and select scopes. 3. Copy the revealed secret immediately and store it in your secrets manager. 4. Use **Disable** to temporarily revoke a key without deleting it. Deleting is permanent. Key secrets are shown once, at creation time. You can edit scopes later, but rotate the key if the secret may have been exposed. ## Storage hygiene * Keys are server-side credentials. Do not ship them to browsers, mobile clients, or any environment you don't control. * Rotate keys when team members leave or when one might have been exposed. * Each key tracks `last_used_at` and `last_used_ip` so you can spot dormant or suspicious keys. * Calls against disabled, expired, or revoked keys return `401 invalid_api_key`. * Mint one key per environment and per process. Don't reuse production keys in CI. Each key has its own rate-limit bucket, usage trail, and Community Review reputation. ## The scopes Every key carries `read` plus any explicit permissions you grant. Endpoints that require a scope you don't have return `403 insufficient_scope`; the message names the missing scope. | Scope | Tier required | Required for | | ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `read` | Any | All read endpoints (search, entities, mentions, appearances, alert history). Granted automatically on every key; cannot be removed. | | `monitors:write` | Any paid | `POST` / `PATCH` / `DELETE` on `/v1/monitors*`, including monitor tracker mutations. | | `trackers:write` | Any paid | `POST` / `PATCH` / `DELETE` on `/v1/trackers*`. | | `recommendations:read` | **Pro+** | `GET /v1/recommendations`, `GET /v1/entities/{id}/recommendations`, `GET /v1/channels/{id}/sponsors`, `GET /v1/mentions?details=full`, and the `recommendations_summary` blocks on entity and channel reads. | Commercial intelligence access is premium because it parses creator ad reads, sponsors, and endorsements at scale. It requires both a **Pro+ tier** (`pro_plus`, `ultra`, `teams`, `enterprise`) and `recommendations:read`. On lower tiers, commercial routes return `403 recommendations_not_enabled` regardless of scope. See [Commercial intelligence](/commercial-intelligence) or check your plan from [Pricing](https://arcmira.com/pricing). ### Choosing scopes * **Read-only integrations** (analytics, dashboards, BI exports): mint a key with `read` only. That key cannot create or delete anything. * **Automation that creates trackers** (CRM enrichment, monitor sync, GTM signals): needs `trackers:write`, and `monitors:write` if it also manages monitors. * **Commercial intelligence integrations** (advertiser dashboards, sponsor research, ad-spend modeling): need `recommendations:read` on a Pro+ plan. On Pro+ plans the dashboard selects it by default for new keys. ## Verifying a key The fastest sanity check is `/v1/me`: ```typescript TypeScript theme={null} const res = await fetch('https://api.arcmira.com/v1/me', { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` }, }); const me = await res.json(); ``` ```python Python theme={null} import os, httpx me = httpx.get( 'https://api.arcmira.com/v1/me', headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"}, ).json() ``` ```bash cURL theme={null} curl https://api.arcmira.com/v1/me \ -H "Authorization: Bearer $ARCMIRA_API_KEY" ``` ```json Response theme={null} { "user_id": "usr_...", "tier": "pro_plus", "scopes": ["read", "monitors:write", "recommendations:read"], "rate_limit": 240, "recommendations_api_enabled": true, "usage": { "rows_used": 1234, "rows_remaining": 98766, "monthly_rows": 100000, "current_spend_cents": 0 } } ``` * `recommendations_api_enabled` is the tier-level gate: `true` only on Pro+ tiers, independent of scopes. If it's `false`, commercial routes will 403 even with the scope attached. * `usage` shows the row budget; check it before metered pulls. `/v1/me` costs 0 rows, though like every authenticated route it returns `402 quota_exceeded` once your pool is exhausted with on-demand disabled. ## Error shape on insufficient scope ```json theme={null} { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "API key requires monitors:write.", "doc_url": "https://docs.arcmira.com/errors#insufficient_scope", "request_id": "req_..." } } ``` The fix is to edit the key or mint a new key with the right scopes from [Dashboard → API Keys](https://arcmira.com/dashboard?tab=api-keys). For commercial scopes you also need a Pro+ plan.