--- name: status-server-api description: Use when reading or driving a running Plaiiin Status server from Claude — checking what is currently red, reading the probe tree or a probe's history, marking a red node or todo as handled (with or without a ticket, through a tracker such as the Workflow server), or authoring probes, commands and their dashboard layouts (widgets, tiles) over the REST API. Covers X-API-Key auth, the /api/** boundary that makes wrong paths look like a login redirect, the role gate on probe authoring, and the version store that makes a plain save refuse. Also covers the credentials store — how a probe authenticates to what it monitors. Your own API key lives in ~/.plaiiin/status-server/env; read that before asking anyone for one. --- # Driving a live Status board This skill is for talking to a **running** Status server. For modelling infrastructure and authoring probe definitions in config, see `status-server-ops`. ## API access — set once, never asked again Both skills read `~/.plaiiin/status-server/env`. Put your server and key there and no session needs to ask you for them. (This is *your* access to the API — not to be confused with the **credentials store**, which holds the secrets probes use to reach the things they monitor.) ```bash mkdir -p ~/.plaiiin/status-server && chmod 700 ~/.plaiiin/status-server cat > ~/.plaiiin/status-server/env <<'EOF' STATUS_URL=https://status.example.com STATUS_API_KEY=twk_… EOF chmod 600 ~/.plaiiin/status-server/env ``` Load it in any shell: ```bash set -a && . ~/.plaiiin/status-server/env && set +a ``` Environment variables of the same name win if already set, so a one-off override still works. If the file is absent **and** the variables are unset, that is the only time you should be asked for a key. ### Getting a key | Route | How | |---|---| | **Web UI** | Click your name (bottom left) → **Account** → the **API Keys** card → name it → *Create*. The raw key is shown **once** — copy it straight into the file above. | | **API** (needs an existing key) | `POST /api/user/api-keys` with `{"name":"…"}` | List or revoke yours with `GET /api/user/api-keys` and `POST /api/user/api-keys/{id}/revoke`. **A key inherits the roles of the user who minted it** — there is no per-key scoping. So the account you are signed in as when you click *Create* decides what the key can do: | Signed in as | Key can | |---|---| | an account with **no** Status role | `GET /api/user/profile` and nothing else — every other `/api/**` path answers `403` | | an ordinary user (any one role) | read state, read history, mark and clear handled references | | `STATUS_ADMIN` / `INFRA_ADMIN` | all of the above **plus** `/api/ide/**` — writing probe and command scripts that execute on every monitored host, and writing config | | `STATUS_ADMIN` alone | the tier above that: releasing and activating a version, uninstalling, and adding or removing a library | ⚠️ **A `403` on a read as plain as `/api/tree` means the account has no Status role yet** — not that the endpoint is admin-only. Anonymous still gets `401`; that distinction is the whole difference between "log in" and "ask an admin for a role". Prefer a key minted by a non-admin account for anything ambient (dashboards, bots, a long-running assistant session). Reach for an admin key only while authoring, and revoke it after. ### Scoping a key to less than yourself A key inherits its owner's roles by default. Pass `roles` to narrow it: ```bash curl -s -X POST -H "$K" -H 'Content-Type: application/json' \ -d '{"name":"dashboard","roles":["VIEWER","HISTORY_USER"]}' \ "$STATUS_URL/api/user/api-keys" ``` Roles: `VIEWER` `HISTORY_USER` `HISTORY_CONFIG` `INCIDENT_RESPONDER` `INCIDENT_MANAGER` `DRILL_RESPONDER` `DRILL_MANAGER` `PROBE_EDITOR` `WORK_USER` `STATUS_ADMIN` `INFRA_ADMIN`. `INCIDENT_RESPONDER` and `INCIDENT_MANAGER` still exist and gate nothing since `v1.0.0-pre.13`. `WORK_USER` gates the work lane and the todos probes report, and it **hides** rather than disables: a key without it does not see the lane at all. If a board's work column looks empty or missing, check this role before checking the probes. | Property | Behaviour | |---|---| | Omit `roles` | The key inherits everything you have — the historical default | | Ask for a role you lack | Refused with `roles_not_held` and the list of what you do have | | Owner loses a role later | Every key they minted loses it too, at the next request | | A scoped key mints a key | Bounded by **its own** scope, not its owner's — it cannot climb out | The intersection is computed per request rather than frozen at mint time, which is what makes the last two rows true. **Use this for anything ambient.** A key in a config file, a dashboard, a bot or a long-running assistant session should be `VIEWER` + `HISTORY_USER`, not an admin key — an admin key can `POST /api/ide/probe-save`, which executes JavaScript on every monitored host. Keep an admin key for authoring sessions and revoke it after. ⚠️ Servers built before 2026-08-27 have no `roles` column; a `roles` list is ignored there and the key inherits everything. Check with `GET /api/user/api-keys` — scoped keys report their `roles`. ⚠️ **If a key returns `401 {"error":"User not found"}`**, the key itself is fine — the account that owns it no longer resolves in the identity directory. That happens when the directory is re-imported and user ids change. Mint a fresh key as a current user; revoking and re-issuing against the old account will not help. ### ⚠️ The `/api/**` boundary — the confusing failure `ApiKeyAuthFilter` is registered **only** on `securityMatcher("/api/**")`. A key presented on any other path is not merely rejected — the request falls through to the browser security chain and you get a **302 to the login form**, which reads like a broken key or a down server. It is neither: it is the wrong path. If a call redirects to `/app/login`, check the path before you check the key. ### 🚨 A `302` does not always mean auth `302 → /app/login` has **three** causes, and only one is about your key: | Cause | Tell | |---|---| | Path is outside `/api/**` | Check the path first | | Key invalid / owner unresolvable | Body is `{"error":"Invalid API key"}` or `{"error":"User not found"}` — a 401, not a 302 | | **A required query parameter is missing** | The request never reaches the handler; the error dispatch redirects | **Fixed on builds from 2026-08-27.** A missing parameter now returns a proper `400 {"status":400,"error":"Bad Request","path":"…"}`. On an older build it redirects instead: a call that lacks a required parameter (`GET /api/probes/history` without `probe=`, for one) lands on the login page, while the same call with the parameter returns `200`. Nothing in the response says "you forgot a parameter" — it looks exactly like being logged out. **If you get a 302 on a server that old, check the endpoint's required parameters before suspecting your credentials.** **A 302 can also mean a wrong query-param name**, not a wrong path. Spring's missing-parameter error is an ERROR dispatch that re-enters the filter chain, so on a chain that does not permit that dispatch it comes back as a redirect to the login form — indistinguishable from a bad key, and it sends you to check credentials that were never the problem. **On any 302, check the endpoint's parameter names before suspecting your key.** `/api/ide/probe-source` was the worst case, taking `?name=` while its neighbour `/api/ide/probe-definition` takes `?id=`. It now accepts either spelling and answers a missing one with a 400 that names both; on a server older than 2026-08-27, `?id=` 302s there. Every JSON endpoint lives under `/api/**` — that invariant holds codebase-wide as of 2026-08-27. On older builds a few served JSON from outside it (notably the infrastructure config, at `/admin/infrastructure/api/config`) and were unreachable with a key. ## Reference files | File | Covers | |---|---| | `references/api-surface.md` | **Every endpoint**, grouped by area, generated from the server source, with 🔒 marking the role-gated ones. Start here to find something. | | `references/api-endpoints.md` | Hand-written detail on the main endpoints — params and response shapes. | | `references/endpoints.md` | The wider surface, including admin and agent routes. | The tables below are the working subset; the references are authoritative. ## Start here: `GET /api/capabilities` One request returns every vocabulary you need to write a valid config, read from **this** server rather than from documentation that may not match it: ```bash curl -s -H "$K" "$STATUS_URL/api/capabilities" ``` | Key | Contains | |---|---| | `probeTypes` · `probeStates` · `dataTypes` | `HTTP_HEALTH`…`MAPPED_JSON`; `OK`/`WARNING`/`ERROR`/`UNKNOWN`; history types | | `paramTypes` · `outputTypes` | Read from the installed catalog, so they describe what this server actually has | | `widgets` | `card` · `plate` · **`both`** · `cardOnly` · `plateOnly` — see the note below | | `tileSizes` · `panelWidthUnits` | Canonical spans; the panel is 4 units wide | | `serviceTypes` | Which `type:` values exist — **check here first** if a `type:` seems to do nothing | | `probeCatalog` | Every installed probe id | ⚠️ **Use `widgets.both`** for tiles on the probe card. A widget the card cannot render produces an empty cell, silently — the response says so too. If this endpoint 404s you are on a build from before 2026-08-27. ## Reading state | Endpoint | Use | |---|---| | `GET /api/status/summary` | **Start here** for "is anything wrong": `errors` `warnings` `unknown` `muted`, active mutes, work, `untrackedIssues`, and a flat `probeDetails` list (name, state, uptime, last message). About 20 KB. Builds from 2026-10-08 on; older ones answer 404, use `/api/status` there. | | `GET /api/status` | The whole board as the web app draws it: both trees with every probe's sparklines. **2.8 MB** on a 75-probe board, every probe twice — too big to read whole; use the summary unless you need a node's `result`. | | `GET /api/tree` | The **full** probe tree. The authoritative view: use it to confirm a `ref` actually resolved and a probe actually ran. | | `GET /api/global` | Tab list / global SPA state. | | `GET /api/events` | Recent state transitions. | | `GET /api/probes/history?probe=&resolution=5s` | Time series for one probe. Resolutions step up (`5s`, `1m`, …) — ask for the coarsest that answers the question. | | `GET /api/probes/history/list` | Which probes have history at all. **A probe with no history has never run** — that is the trap-1 signature from `status-server-ops`. | | `GET /api/probes/snapshot?probe=` | Current value of every path for one probe. | | `GET /api/untracked-issues` | Things failing that nobody has marked handled or muted — the natural triage queue. The same entries as `untrackedIssues` in the summary, without the checks of an agent the configuration does not list. | | `GET /api/presence` | Who is online. | | `GET /api/agents` | The agents, with their heartbeat data. | | `GET /api/infrastructure/config` | The whole declared infrastructure — hosts, projects, dependencies, thresholds. | | `GET /api/infrastructure/types` · `GET /api/infrastructure/hosts` | Service-type catalog with param metadata; host names. | | `GET /api/capabilities` | Vocabularies, incl. `probeCatalog` — every installed probe id. | ⚠️ **`/api/hosts`, `/api/types` and `/api/active` do not exist** (404). Earlier revisions of this file listed them. Use `/api/infrastructure/hosts`, `/api/infrastructure/types` and `/api/tree` respectively. Anything taking a `probe` parameter answers `400` without it, not an empty result. Probe names in the tree are **whitespace-sensitive path strings**: `Agents / app-01.example.com / Web Reachable`. Copy them from `/api/tree` rather than retyping — a near-miss returns empty, not an error. ## Handled — saying who is on a red, with or without a ticket A **handled reference** is one small fact on a board node or a todo: somebody is on it, and here is where (a ticket URL, or just a note). The covered nodes go quiet in rollups and drop out of `untrackedIssues`, `/api/untracked-issues` and the bell (the error/warning counters still count it). **Alerts keep firing** — handled is for people reading the board; a mute is what silences notifications. Builds from 2026-10-09 on; older ones answer `404` on `/api/handled`. **Mark before you investigate, not after.** A red that two people (or an agent and a person) work on at once is how a fix gets made twice. ```bash K="X-API-Key: $STATUS_API_KEY" # what is handled right now (add ?history=true for cleared ones and why, # or ?probe= for the marks of one check, cleared ones included) curl -s -H "$K" "$STATUS_URL/api/handled" # mark a probe handled — path is the FULL probe name, copied from /api/tree curl -s -X PUT -H "$K" -H 'Content-Type: application/json' \ -d '{"target":{"kind":"node","type":"probe","path":"Agents / app-01.example.com / Web Reachable"},"note":"Looking at the proxy","replaces":null}' \ "$STATUS_URL/api/handled" # with a ticket: url + system + externalId (the same system+externalId again changes nothing) curl -s -X PUT -H "$K" -H 'Content-Type: application/json' \ -d '{"target":{"kind":"node","type":"app","path":"shop / Checkout"},"url":"https://jira.example.com/browse/OPS-12","system":"jira","externalId":"OPS-12","replaces":null}' \ "$STATUS_URL/api/handled" # clear — query parameters, path URL-encoded curl -s -X DELETE -H "$K" \ "$STATUS_URL/api/handled?kind=node&type=probe&path=Agents%20%2F%20app-01.example.com%20%2F%20Web%20Reachable" # tickets through a configured tracker (the Workflow server today) curl -s -H "$K" "$STATUS_URL/api/handled/trackers" # [{id, displayName, kind}] curl -s -H "$K" "$STATUS_URL/api/handled/trackers//search?q=proxy" # [{id, title, url, state}] curl -s -X POST -H "$K" -H 'Content-Type: application/json' \ -d '{"target":{"kind":"node","type":"probe","path":"Agents / app-01.example.com / Web Reachable"},"title":"Proxy answers 502"}' \ "$STATUS_URL/api/handled/trackers//tickets" # creates the ticket AND marks it handled ``` | Target | `type` | `path` | |---|---|---| | one probe | `probe` | the full probe name (`result.probeName`) | | a branch: service, app, project | `service` `app` `project` | the infrastructure path; covers every probe under it | | a host | `host` | the bare host name; covers `Agents / / …` and `Hosts / / …` | | one todo | `probe`, with `kind: "todo"` and `todoId` | the full name of the probe that reports it | | Trap | | |---|---| | A short display name as `path` | Refused at set time: `404 unknown_target`, nothing stored. Copy `path` from `/api/tree` | | A host as `type: project` | Also `404 unknown_target`. A host is `type: host` | | It clears by itself | After every covered probe is continuously `OK` for 1 h (`clearAfter` overrides it per reference: seconds such as `600`, or a duration such as `"30m"`); `UNKNOWN` never counts as `OK`. A todo clears when its probe stops reporting it | | One per target | A new `PUT` on the same target replaces the active one (the old one is cleared `manual`) | | Your clears read `tracker` | Every `X-API-Key` clear records reason `tracker`; only a browser session or a bearer token records `manual` | | Still dimmed after a clear | Another reference covers the node: one on a branch or host above it, or on a branch that refers to it. `handledBy.targetPath` names where it sits. (On a server older than `v1.0.0-pre.13`, an open workflow record can be the reason too) | | Tracker errors | `502 {"error":{"code":"tracker_error","message":…}}` — the message is the tracker's reason. `did not answer within 10 s` on a create adds `the ticket may still have been created there`: search before you create again | | `409 conflict` from `…/tickets` with `current` | Someone is already on that target (`current` says who); no ticket was filed. Link to theirs, or create with `"replaces": ` if you really replace it | | `not_marked` (400 or 500), or `409 conflict` with a `ticket`, from `…/tickets` | The ticket WAS created (it is in the answer's `ticket`); only the mark failed, or someone marked the target while it was being created. Do not retry, or you file it twice — `PUT /api/handled` with the ticket's `url` instead | | `409 conflict` from `PUT /api/handled` | You sent `replaces` (`null` = nobody) and the target holds something else: `current` beside `error`. Nothing of yours is stored. Send `"replaces": null` on a mark unless you mean to replace `current.id` — without `replaces` a PUT silently replaces whoever is on it | | `500 not_stored` from `PUT /api/handled` | The write itself failed (disk full, a locked database); nothing is stored. Try again once the server is healthy | | A 400 | `error.code` says which: `missing_target`, `missing_fields` (names in `error.missing`), `bad_target`, `bad_clear_after`, `invalid_field` (`url` 2048, `title` 300, `externalId` 200, `note` 2000 characters; the message names the field), `bad_request` | Tracker settings (🔒 `STATUS_ADMIN` or `INFRA_ADMIN`): `GET /api/handled/trackers/config` lists them all, `PUT /api/handled/trackers/config/{id}` creates or replaces one, `DELETE` on the same path removes it. There is no `GET` for a single one, and `config` is not a valid tracker id. The Workflow API key sits in the credentials store and is referenced by `credentialName`. Full list: `references/api-surface.md` → *Handled*. ## Incidents — there are none; mark the red handled ⛔ **Status keeps no incident records.** Since `v1.0.0-pre.13` (2026-11-16) the embedded workflow engine is gone: `/api/workflows/**` answers `404`, as `/api/incidents` has for longer, and the web app has no Incident tab and no workflow type editor. Status says **who is on a problem**; the ticket, if there is one, lives in a tracker. | You want to | Do | |---|---| | say you are on a red | `PUT /api/handled` with a `note` (see *Handled* above) | | open a ticket for it | `POST /api/handled/trackers//tickets`, which files it and marks the target in one call | | point at a ticket that exists | `PUT /api/handled` with its `url` (and `system`, `externalId`) | | read what happened on a check | `GET /api/handled?probe=`: every mark that covered it, cleared ones included, with who, note, ticket, from when to when and why it ended. In the web app: the clock button on the check's row | | read the state changes | `GET /api/events`, or `GET /api/probes/history?probe=&resolution=5s` | Prefer marking a red over letting it sit unexplained: an unexplained red is how people learn to ignore red. **On a server older than `v1.0.0-pre.13`** the engine still runs: `GET /api/workflows/types` answers `200`, and an open record there also marks a check handled (its `handledBy` carries only `workflowType`, `instanceId` and `title`, and the handled API cannot clear it). Its records are not migrated by an upgrade; they stay as files in `/status/data/workflows` on the data volume. ## Writing configuration `POST /api/infrastructure/config` with the full config object. It saves, reloads the scheduler and records a history entry in one call — `200 {"status":"ok"}`, or `409`/`400` with `{"error": {"code", "message"}}`. Requires `STATUS_ADMIN` or `INFRA_ADMIN`. Add `?dryRun=true` to get the same report **without writing anything** — refs resolved and unverified, probes bound to agents that do not exist, how many probes the config would generate. Do that before every change. ⚠️ A real save does not refuse a broken config; it applies it and reports the problems alongside `status: "ok_with_warnings"`. Read the response body, not just the status code. Details and the lossy round-trip caveat: `status-server-ops`. ## Probe authoring over the API The Probe IDE's backend is fully scriptable under `/api/ide/*`: | Endpoint | Use | |---|---| | `GET /api/ide/probes` · `GET /api/ide/list` | What is installed. | | `GET /api/ide/probe-source` · `GET /api/ide/probe-definition` | Read a probe's `check.js` / `probe.yml`. Both accept `?name=` or `?id=`, plus `?ref=`. | | `POST /api/ide/probe-create` | New catalog probe, authored here rather than imported. | | `POST /api/ide/probe-save` · `POST /api/ide/probe-definition` | Write `check.js` / `probe.yml` **at a `ref`**. | | `GET /api/ide/probe-versions?id=` | The version bar: `live`, `liveDirty`, `origin`, `releases[]`, `dev[]`. | | `POST /api/ide/probe-version-create` · `-release` · `-activate` · `-delete` | The authoring loop below. | | `POST /api/ide/test` | Run a script server-side against sample params. | | `POST /api/ide/test-on-agent` → `GET /api/ide/test-on-agent/{id}` | Run it **on a real agent** and poll the result. Async: the POST returns an id. `{agent, id}` runs the INSTALLED probe; `{agent, ref}` runs that version; `{agent, source}` runs an inline script and wins over both. | | `GET/POST /api/ide/probe-bindings` | Which hosts a probe is bound to. | | `GET/POST /api/ide/probe-svg` | The probe's infographic. | | `GET/POST /api/ide/command-*` | The same surface for agent commands, **including versions** — `command-versions`, `command-version-create`, `-release`, `-activate`, `-delete`. | ### 🚨 A plain save is refused now — probes AND commands are versioned Every entry has three kinds of version, named by a `ref`: `live` (what agents run), `dev/