HTTP API
The API the console uses, available for automation.
3AM serves its API and console on one port (8700 by default). Everything the console does goes through this API.
Authentication
Send the console admin token as a bearer token:
export THREEAM=http://127.0.0.1:8700
export TOKEN=... # see "I lost the console admin token" in Troubleshooting
curl -s -H "Authorization: Bearer $TOKEN" $THREEAM/v1/episodes?limit=5/health, /v1/status and /v1/login need no token. POST /v1/events uses the separate ingest token.
Calls that change something take by, the person asking, which is recorded in the audit log. Halt, resume and
autonomy changes require it.
Status
| Method and path | Returns |
|---|---|
GET /health | {"status": "ok"} |
GET /v1/status | Version, fingerprint, mode (setup, configuring, operating), licence (state, customer, expires_at, in_grace), setup progress, the audit log's head |
POST /v1/login | {"token": "…"} → 200 if the token is right, 401 if not |
POST /v1/licence | {"licence": {…the licence file's JSON…}} installs a licence. 409 if one is mounted from a file |
Incidents
| Method and path | Returns |
|---|---|
GET /v1/episodes?limit=100 | Recent incidents, newest first |
GET /v1/episodes/{id} | One incident: signals, verdicts, evidence, proposal, policy decision, rehearsal, approvals, outcome, and its full timeline from the audit log |
GET /v1/approvals | Approval requests with their decisions and who made them |
GET /v1/digest?days=1 | The digest for the last N days, as data and as Markdown |
GET /v1/estate | The discovered services, repositories, owners and dependencies |
Autonomy and the halt switch
| Method and path | Body | Effect |
|---|---|---|
GET /v1/autonomy | Each service's level and readiness, and whether 3AM is halted | |
POST /v1/autonomy | {"service": "payments", "level": "off|shadow|L1", "by": "jane.doe"} | 202. Lowering is immediate; raising to L1 asks for approval first |
POST /v1/halt | {"by": "jane.doe", "reason": "change freeze"} | Refuse every action |
POST /v1/resume | {"by": "jane.doe"} | Release the halt |
Connectors and policy
| Method and path | Body | Effect |
|---|---|---|
GET /v1/connectors/catalogue | Every connector kind and its settings | |
GET /v1/connectors | Configured connectors, with secrets masked and each one's last problem | |
POST /v1/connectors/test | {"kind": "prometheus", "settings": {…}} | Try settings without saving: health, and what it found |
PUT /v1/connectors/{name} | {"kind": "prometheus", "settings": {…}} | Add or update a connector. Secrets are stored in the data directory, never returned. A blank secret keeps the stored one |
DELETE /v1/connectors/{name} | Remove a connector added in the console | |
POST /v1/discover | Start discovery (repositories, estate). Returns a job id | |
GET /v1/jobs/{id} | A discovery job's progress | |
GET /v1/policy | The policy in force | |
PUT /v1/policy | The policy | Replace the policy. The default autonomy may only be off or shadow. 409 if the policy is mounted from a file |
Connectors and the policy defined in files under /etc/3am can't be changed over the API (409): edit the files.
Audit log
| Method and path | Returns |
|---|---|
GET /v1/ledger | Events, newest first. Filters: type (prefix, such as action.), trace (an incident id), actor (prefix), q (text), before_seq, limit (max 2000), order=asc |
GET /v1/ledger/verify | The integrity report (same as ledger-verify) |
# Every action 3AM executed, with who approved it
curl -s -H "Authorization: Bearer $TOKEN" "$THREEAM/v1/ledger?type=action.executed&limit=50"Events
POST /v1/events adds an event to the audit log, for example a change someone made by hand during an incident. It
needs THREEAM_INGEST_TOKEN set on 3AM, sent as the bearer token.
curl -s -X POST $THREEAM/v1/events -H "Authorization: Bearer $INGEST_TOKEN" -H 'Content-Type: application/json' \
-d '{"type": "human.action", "actor": "jane.doe", "reason": "restarted the payments pod by hand", "data": {"service": "payments"}}'type must start with one of: signal., retrieval., model., check., decision., approval., action.,
outcome., config., connector., system., human.. Returns 201 with the event's sequence number and hash.
Errors
Errors are JSON, {"error": "…"}, with the usual codes: 400 for a bad request, 401 without a valid token, 404, 409
when something is managed in a file or no licence is installed yet, 503 while 3AM is not yet operating.