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

# Monitors

> Standing entity tracking with alert delivery to email, Slack, and HMAC-signed webhooks. Trackers, monitors, and alert history.

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

  <p className="callout-body">
    Stop reading and copy the [Monitors coding agent reference](/monitors-for-coding-agents) into your agent. It is self-contained, including webhook signature verification.
  </p>
</div>

Monitors are the standing half of Arcmira: a Search interest that keeps firing as new media lands. The model is two nouns:

* A **tracker** watches one entity (by name + type) and fires whenever new media matching it is analyzed.
* A **monitor** is a named group of trackers with shared delivery settings: email cadence, a Slack channel, a webhook endpoint.

Tracking is entity-level, not keyword-level. A tracker on `Apple (organization)` will not fire for fruit, and a tracker on the topic `weather modification` catches the concept however it is phrased.

## Key capabilities

| Capability       | What it does                                                        |
| ---------------- | ------------------------------------------------------------------- |
| Trackers         | Watch any person, organization, product, topic, or channel          |
| Monitors         | Group trackers; own the delivery settings                           |
| Email delivery   | `realtime`, `hourly`, or `daily` digests with configurable day/time |
| Slack delivery   | One-click OAuth in the dashboard, then route alerts to a channel    |
| Webhook delivery | HMAC-signed POSTs to your endpoint, with retries and auto-disable   |
| Alert history    | Poll the last N deliveries per monitor or tracker                   |

Every alert is evidence, not just a ping: the matched entity and tracker, the video and channel, the exact timestamp, sentiment, a context quote, and a deep link to watch the moment.

## Common use cases

<AccordionGroup>
  <Accordion title="Catch every mention of your company on Tier-1 shows">
    Track your organization and your competitors; alerts land in Slack minutes after a new episode is analyzed, with the clip and the sentiment. Amplify the praise while it's hot, answer the attack before it trends.
  </Accordion>

  <Accordion title="Watch a narrative before it steers the conversation">
    Track a topic entity. Know the moment fringe or mainstream voices pick it up, with sentiment per mention.
  </Accordion>

  <Accordion title="Stand up monitoring from your own systems">
    Create monitors and trackers programmatically from your CRM or portfolio list, deliver to a webhook, and drive your own dashboards or the next agentic action.
  </Accordion>
</AccordionGroup>

## Quickstart: the full lifecycle

<Steps>
  <Step title="Create a monitor with delivery settings">
    ```bash theme={null}
    curl -X POST 'https://api.arcmira.com/v1/monitors' \
      -H "Authorization: Bearer $ARCMIRA_API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Competitor watch",
        "icon": "radar",
        "color": "indigo",
        "notifyEmails": ["ops@example.com"],
        "notifyFrequency": "realtime",
        "notifyWebhook": true,
        "webhookUrl": "https://example.com/hooks/arcmira"
      }'
    ```

    Requires `monitors:write`. Webhook delivery is a paid-tier feature; Slack is available from Free.
  </Step>

  <Step title="Create a tracker, then attach it">
    Trackers are created standalone, then attached to a monitor by ID:

    ```bash 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": "Ramp", "entityType": "organization" }'
    # -> { "tracker": { "id": "trk_9f2ab4c8d1e6", ... } }

    curl -X POST 'https://api.arcmira.com/v1/monitors/mon_abc123/trackers' \
      -H "Authorization: Bearer $ARCMIRA_API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{ "trackerIds": ["trk_9f2ab4c8d1e6"] }'
    ```

    `entityType` is one of `person`, `organization`, `product`, `topic`, `channel`. Trackers left standalone still fire; they use their own per-tracker delivery settings instead of the monitor's.
  </Step>

  <Step title="Verify with alert history">
    ```bash theme={null}
    curl 'https://api.arcmira.com/v1/monitors/mon_abc123/alerts?n=25' \
      -H "Authorization: Bearer $ARCMIRA_API_KEY"
    ```

    Every delivery attempt is a row: channel, status, timestamps, and the tracker that fired. Use it to verify your integration end-to-end or to power a recent-activity feed.
  </Step>

  <Step title="Receive and verify webhooks">
    Deliveries are HMAC-signed (`X-Arcmira-Signature`). Verification code and the full payload schema live in the [coding agent reference](/monitors-for-coding-agents#webhooks).
  </Step>
</Steps>

## Choosing well

* **Tracker vs monitor.** One entity to watch: a tracker. A program of entities sharing a destination (a Slack channel per client, a webhook per environment): a monitor. Per-tracker delivery overrides exist for exceptions; don't build one monitor per entity.
* **One-shot vs standing.** If you only need the answer today, pull [Search](/search) mentions and skip tracking. Trackers earn their keep when the interest outlives the query.
* **Realtime vs digest.** `realtime` email/Slack/webhook for anything you'd act on within the hour (brand defense, crisis). `daily` digests for awareness-level interests; they batch to `digestTime`.
* **Alert cost.** Each fired occurrence debits **100 rows** from the shared pool, once per occurrence regardless of how many channels it fans out to.
* **Polling vs webhooks.** Webhooks push within minutes of analysis. Poll alert history when you can't host an endpoint, when auditing delivery, or when backfilling after downtime; the two compose (webhook for speed, polling for reconciliation).

## Constraints

* Scopes: `monitors:write` / `trackers:write` for mutations; `read` for all GETs. Send `Idempotency-Key` on every POST/PATCH.
* Alerts bill 100 rows per fired occurrence; monitor and tracker CRUD is free.
* Delivery tiers: Slack from Free; realtime email and webhooks on paid tiers (Free email is daily digest).
* Alerts fire for **recently published media** (roughly a 14-day publish window) as it is analyzed; this is monitoring, not retroactive search. Backfill history with [Search](/search).
* Matching is by resolved entity (name + type), the same resolution Search uses.
* If a usage cap pauses delivery, missed alerts are surfaced in the dashboard and can be replayed once the cap lifts.

## Community Review

Any alert that fired is disputable, free, with `type: "monitor_alert"` on `POST /v1/feedback`: wrong entity, wrong media, duplicate, should-not-have-fired, or the inverse, a `missed_alert` you expected (submitted with the video URL as evidence). Corrections key off the alert row ID from alert history, and you can check review status later with `GET /v1/feedback/{feedback_id}`. Details and the full issue set: [Community Review](/feedback#monitor-alerts).

## Next

* [Monitors for coding agents](/monitors-for-coding-agents): all endpoints, the alert object, webhook payloads, and signature verification.
* [Search](/search): resolve entities before you track them.
* [API reference](/api-reference/monitors/create-monitor): interactive playground.