Ops API

Admin APIs of the Full preset (internal/modules/ops), implemented in examples/full-single. The full schema is in the app's api/openapi.json and at /docs. Decisions: ADR-0026, ADR-0031, ADR-0033, ADR-0036, ADR-0037, ADR-0038, ADR-0040.

Authentication#

/ops/* requests use a signed-in session: a browser's session cookie, or a bearer token from POST /v1/auth/login with "transport": "bearer". The account needs a platform role (authentication guide):

go run ./cmd/api grant-role you@example.com platform_admin
TOKEN=$(curl -s -X POST http://127.0.0.1:8080/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"your password","transport":"bearer"}' | jq -r .token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/ops/settings

Changes are attributed to the signed-in user in history, job metadata and audit events.

Permissions#

Missing permission: 403 forbidden.

Conventions#

• Errors are application/problem+json with code, detail and request_id.
• Changes send the version they last read; a newer version returns a *_version_conflict error. Read again and retry.
• Unknown request fields are ignored.

Runtime settings#

curl -X PUT http://127.0.0.1:8080/ops/settings/example.ping_message \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"hello","version":0,"reason":"demo"}'

{
  "key": "example.ping_message",
  "kind": "string",
  "group": "example",
  "description": "Reply of GET /v1/ping. …",
  "value": "hello",
  "default": "pong",
  "modified": true,
  "invalid_stored_value": false,
  "version": 1,
  "updated_at": "2026-09-14T12:00:00Z",
  "updated_by": "usr_mfrggzdfmztwq2lk",
  "reason_required": false,
  "restart_required": false,
  "restart_pending": false,
  "constraints": {"max_len": 100}
}

Retention#

How long data is kept is a runtime setting per kind of data (ADR-0051), so changes need the setting's reason, appear in its history and audit log, and apply on every instance without a restart. GET /ops/retention (ops.settings.read) lists them:

Each policy shows retention (a Go duration) and retention_seconds, the enforcing job with its last_run and next_run_at, and oldest_at for the data the retention job deletes. The job deletes 5,000 rows per statement until nothing is older, and records a retention.purged audit event with the row count and cutoff for each kind of data, so a shortened retention stays visible after the rows are gone.

curl -X PUT http://127.0.0.1:8080/ops/settings/audit.retention \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"17520h","version":0,"reason":"two-year compliance requirement"}'

Maintenance mode#

Turn it on with the maintenance.enabled setting (a reason is required); every instance applies it within a second (ADR-0051). While it's on, requests answer 503 with problem code maintenance, detail set to maintenance.message (a generic message when empty) and a Retry-After header from maintenance.retry_after (5 minutes by default).

Still served, so load balancers keep instances in rotation and staff can turn it off: /livez, /readyz, /version, /openapi.json, /docs, /.well-known/*, /ops/* and /v1/auth/*. Sign-in works for everyone, but every product route after it answers 503.

curl -X PUT http://127.0.0.1:8080/ops/settings/maintenance.message \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"Upgrading the database until 10:00 UTC","version":0}'
curl -X PUT http://127.0.0.1:8080/ops/settings/maintenance.enabled \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":true,"version":0,"reason":"database upgrade"}'

When nobody can reach /ops, run it where the app's environment is set:

go run ./cmd/api maintenance on --message "Back at 10:00 UTC"
go run ./cmd/api maintenance off

The command writes the same settings as system:cli, recorded in their history and the audit log.

Job definitions#

curl -X PUT http://127.0.0.1:8080/ops/jobs/definitions/heartbeat \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"schedule":"@every 2h","timeout":"30s","version":0,"reason":"less noise"}'

{
  "name": "heartbeat",
  "description": "Logs a heartbeat. …",
  "config":   {"enabled": true, "schedule": "@every 2h", "timeout": "30s", "max_attempts": 3, "queue": "default", "priority": 1},
  "defaults": {"enabled": true, "schedule": "@every 1h", "timeout": "1m0s", "max_attempts": 3, "queue": "default", "priority": 1},
  "modified": true,
  "invalid_override": false,
  "version": 1,
  "updated_by": "usr_mfrggzdfmztwq2lk",
  "next_run_at": "2026-09-14T14:00:00Z",
  "last_run": {"id": 42, "kind": "heartbeat", "state": "completed", "attempt": 1, "…": "…"}
}

A reason is required to disable a job or change an enabled job's schedule.

Job runs#

Run fields: id, kind, queue, state, attempt, max_attempts, priority, created_at, scheduled_at, attempted_at, finalized_at, errors[{at, attempt, message}], request_id, actor_kind, actor_id. Arguments are never returned.

GET /ops/jobs/overview (ops.jobs.read, ADR-0051) summarises job work across every instance:

{
  "queues": [
    {"name": "default", "active": true, "paused": false,
     "available": 0, "scheduled": 3, "running": 1, "retryable": 2, "discarded_last_day": 1}
  ],
  "failing": [{"name": "send_digest", "last_run": {"state": "retryable", "errors": [...]}, ...}]
}

queues lists queues with active workers or unfinished jobs; failing lists job definitions, in the same shape as GET /ops/jobs/definitions, whose most recent run is retrying or was discarded.

Queues#

Audit log#

Stats return the 50 largest groups, with the rest counted in other; group_by=day returns every day with events, in order. A wider window or an unknown grouping returns 422 invalid_audit_filter.

curl -H "Authorization: Bearer $TOKEN" \
  'http://127.0.0.1:8080/ops/audit/stats?group_by=action&action_prefix=auth.&outcome=failure'

curl -H "Authorization: Bearer $TOKEN" \
  'http://127.0.0.1:8080/ops/audit?action_prefix=settings.&limit=20'

{
  "events": [
    {
      "id": 7,
      "occurred_at": "2026-09-14T12:00:00.123Z",
      "recorded_at": "2026-09-14T12:00:00.125Z",
      "actor_kind": "user",
      "actor_id": "usr_mfrggzdfmztwq2lk",
      "action": "settings.value.changed",
      "resource_type": "setting",
      "resource_id": "example.ping_message",
      "outcome": "success",
      "request_id": "req_99c4a38756b2eb8f",
      "trace_id": "951ff1fe97c8f8616496d020314fea38",
      "metadata": {"reason": "demo", "reset": false, "version": 1}
    }
  ],
  "next_cursor": "7"
}

• request_id links an event to its access log line, trace and any jobs the request enqueued.
• ip and user_agent appear on events recorded during a request, such as sign-ins.
• Metadata values under sensitive keys such as password or token are stored as "[REDACTED]"; oversized metadata is replaced with {"metadata_dropped": "too_large"}.
• Events can't be changed. The retention job deletes events older than audit.retention (365 days by default) and records a retention.purged event for each deletion: see Retention.

Releases#

Every instance records its build when it starts (version, commit, build time, whether the tree had uncommitted changes, Go version, host), sends a heartbeat every 30 seconds and marks itself stopped when it shuts down cleanly. An instance is running until it stops or misses three heartbeats, so crashed instances drop out after about 90 seconds. Instances last seen more than 90 days ago are deleted.

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/ops/releases/current

{
  "releases": [
    {
      "version": "v1.4.0",
      "commit": "3f9a1c2b7d4e8a90",
      "instances": [
        {"id": 12, "instance_id": "9b1c…", "version": "v1.4.0", "commit": "3f9a1c2b7d4e8a90",
         "build_time": "2026-09-15T09:58:00Z", "modified": false, "go_version": "go1.26.1", "host": "acme-api-7d9f8-x2kq",
         "started_at": "2026-09-15T10:02:11Z", "last_seen_at": "2026-09-15T10:31:41Z", "running": true}
      ]
    }
  ]
}

Builds without version control information or a link-time version show "version": "dev" and no commit.

System#

GET /ops/system describes the instance that answers (ADR-0051); behind a load balancer, repeat it to reach others, and use GET /ops/releases/instances for the whole fleet. It never includes the database URL, dependency host names, environment variables or settings values.

A failing database still returns 200, with database.status and the postgres check set to error. migrations.pending above 0 means this build's migrations haven't been applied: run go run ./cmd/migrate.

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/ops/system

Email#

{"provider": "smtp", "delivery": "provider", "details": {"host": "smtp.postmarkapp.com", "port": "587", "tls": "starttls", "auth": "username and password"},
 "from_name": "Acme", "from_email": "hello@acme.com", "reply_to": "support@acme.com"}

Resend details are {"api_key": "configured"} or "missing". Change the sender with PUT /ops/settings/mail.from_email (and mail.from_name, mail.reply_to). The test email's delivery appears in GET /ops/jobs/runs?kind=apistock.mail.send. Setup: email guide.

Sign-in methods#

Which sign-in methods this deployment has configured, and what turns the others on (ADR-0045, sign-in provider setup). Permission ops.auth.read (ops_viewer, platform_admin).

Values of secrets are never returned; the same report is printed at start in development and by go run ./cmd/api auth-providers.

Error codes#

Error codes are public API: new ones are added, existing ones never change.

Audit actions#

examples/full-single stores these events in the audit_events table (modules/auditpg) and lists them with GET /ops/audit. Reading the audit log is not itself audited.