# For AI agents and scripts

Everything in the dashboard is in the API. The short version for agents is `/llms.txt`; the full contract is the [API reference](api.md).

## Keys

Make a key in **Settings, Security, API keys** and choose its scope:

| Scope | Can |
|---|---|
| read | See everything (secrets stay masked) |
| write | Add, change, pause, mute, check and delete monitors; incidents; the status page; channel names and events |
| admin | Also channel secrets, settings, import, and the blocked addresses list |

Keys never manage sign-in (passwords, passkeys, the authenticator, sessions) and cannot make other keys. Send the key as `Authorization: Bearer fs_...`. On the server, `farsightd key <name> <scope>` makes one too.

## Habits that keep agents safe

- **Test before saving**: `POST /api/v1/monitors/test` runs a real check of a monitor you have not saved.
- **Use slugs**: `PUT /api/v1/monitors/by-slug/{slug}` creates or replaces, so a plan can be applied twice without duplicates.
- **Preview bulk work**: `POST /api/v1/monitors/bulk` with `"dry_run": true` says what would be created, updated or left unchanged, and which items have errors.
- **Retry safely**: add `Idempotency-Key` to POSTs.
- **Read errors**: a `422` names the fields (`http.url`, `interval_s`) with a sentence each.

## Example: watch a new service

```
curl -s -X PUT https://farsight.example.com/api/v1/monitors/by-slug/orders-api \
  -H "Authorization: Bearer $FARSIGHT_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Orders API", "kind": "http", "group": "Production", "interval_s": 30,
       "http": {"url": "https://orders.example.com/health",
                "json": [{"path": "$.status", "op": "==", "value": "ok"}]}}'
```

## Example: what is broken

```
curl -s -H "Authorization: Bearer $FARSIGHT_KEY" "https://farsight.example.com/api/v1/monitors?status=down"
curl -s -H "Authorization: Bearer $FARSIGHT_KEY" "https://farsight.example.com/api/v1/incidents?state=open"
```

## Live updates

`GET /api/v1/stream` is Server-Sent Events: `check` for every result, `state` when a monitor changes, `incident`, `blind` (Farsight's own internet), and `monitors` when monitors are added or removed.