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.

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.