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

# Monitors & Trackers

> Programmatic entity tracking and recent alert delivery.

Arcmira's tracking primitives are exposed via the API so you can automate them from your own systems.

* A **tracker** watches one entity (by name + type) and produces alerts whenever new mentions match.
* A **monitor** is a named bucket of trackers with shared delivery settings (email, Slack, webhook).

Both surfaces require write scopes:

* `monitors:write` for `POST` / `PATCH` / `DELETE` on `/v1/monitors*`.
* `trackers:write` for `POST` / `PATCH` / `DELETE` on `/v1/trackers*`.

`GET` endpoints only need `read`.

<Tip>
  Send an `Idempotency-Key` header on every `POST` / `PATCH` to make retries safe. See [Idempotency](/idempotency).
</Tip>

## Monitors

### List

```bash theme={null}
curl https://api.arcmira.com/v1/monitors \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
```

### Create

```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": "AI founders",
    "icon": "sparkles",
    "color": "indigo"
  }'
```

### Update / delete

```bash theme={null}
curl -X PATCH https://api.arcmira.com/v1/monitors/mon_abc123 \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "AI founders & infra" }'
```

```bash theme={null}
curl -X DELETE https://api.arcmira.com/v1/monitors/mon_abc123 \
  -H "x-api-key: $ARCMIRA_API_KEY"
```

### Trackers inside a monitor

```bash theme={null}
curl https://api.arcmira.com/v1/monitors/mon_abc123/trackers \
  -H "x-api-key: $ARCMIRA_API_KEY"
```

To attach new trackers, `POST` to `/v1/monitors/{id}/trackers` with the same shape as standalone tracker creation.

## Trackers

### Create

```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": "Sam Altman",
    "entityType": "person",
    "displayName": "Sam Altman (OpenAI)"
  }'
```

`entityType` must be one of `person`, `organization`, `product`, `topic`, `channel`.

### Update / delete

```bash theme={null}
curl -X PATCH https://api.arcmira.com/v1/trackers/tr_xyz789 \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "Sam Altman" }'
```

```bash theme={null}
curl -X DELETE https://api.arcmira.com/v1/trackers/tr_xyz789 \
  -H "x-api-key: $ARCMIRA_API_KEY"
```

## Recent alerts

To inspect delivery state without subscribing to webhooks, pull the last *N* alerts for a monitor or tracker. Default `n=25`, max `100`.

```bash Monitor alerts theme={null}
curl 'https://api.arcmira.com/v1/monitors/mon_abc123/alerts?n=50' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
```

```bash Tracker alerts theme={null}
curl 'https://api.arcmira.com/v1/trackers/tr_xyz789/alerts?n=50' \
  -H "x-api-key: $ARCMIRA_API_KEY"
```

Each alert row includes:

* `id`, `tracker_id`, `monitor_id`
* `entity_id`, `media_id`, `appearance_id`
* `channel` (email / slack / webhook)
* `status`, `final_status`, `error_message`
* `scheduled_at`, `sent_at`, `created_at`
* Embedded `tracker` (entity name + type + display name)
* Embedded `monitor` (id + name) when applicable

Use the alerts endpoint to verify your delivery integration end-to-end, or to power a "recent activity" feed on your own dashboard.

## Roadmap

Webhooks for tracker alerts are on the [roadmap](/roadmap). Until they ship, recent-alerts polling is the recommended pull-side pattern.