API Reference (Complete)#

This page documents every HTTP route exposed in:

• crates/dockrev-api/src/api/mod.rs
• crates/dockrev-supervisor/src/app.rs

Authentication model#

• Public: no auth header required.
• Forward Auth: the ingress may forward trusted identity headers from the upstream auth system, but Dockrev still decides whether a protected route returns data or 401 auth_required.
• Dockrev authorization: Dockrev reads DOCKREV_AUTH_ALLOWED_USER and DOCKREV_AUTH_ALLOWED_GROUP; each accepts a single value, and matching either one is enough when both are set.
• Webhook Secret: requires X-Dockrev-Webhook-Secret matching server config.
• GitHub Signature: requires X-Hub-Signature-256, X-GitHub-Event, and X-GitHub-Delivery.

Dockrev API (/api/*)#

1) Core#

2) Stacks / Services / Version inference#

3) Discovery / Check / Runtime scan / Update#

GET /api/discovery/projects returns active, stopped, missing, or invalid in status. stopped means the saved Compose files are readable and valid but no container is currently running; the linked Stack stays unarchived and can use its existing lifecycle start action. Scan jobs expose stacksStopped and the marked_stopped action. Dockrev auto-archives only when every saved file is ENOENT, with reason auto_archive_compose_files_missing; partial absence, permission/I-O failures, and parse failures remain visible as invalid. Discovery never removes a user archive.

• POST /api/updates contract:

  • scope=service: requires explicit serviceId + targetTag + targetDigest + pullTags.
  • scope=stack|all: requires explicit targets[], each entry shaped as { serviceId, targetTag, targetDigest, pullTags }.

• Service lifecycle contract:

  • GET /api/services/{service_id}/lifecycle-status returns state=running|stopped|partial|unknown, plus activeJob for a queued or running update, rollback, or lifecycle task on that service.
  • POST /api/services/{service_id}/lifecycle accepts { "action": "start" | "stop" | "restart" }. Compose V2 starts with up -d --pull never --no-recreate --no-deps; Compose V1 uses start, which only starts an existing container. Neither path pulls an image, replaces an existing container, or starts dependencies. Start is unavailable under Compose V1 when no container exists. Stop and restart use their corresponding Compose commands.
  • Updates, rollbacks, and lifecycle tasks are serialized per service. Conflicts return 409 with existingJobId. The Dockrev service does not expose this lifecycle operation.

4) Jobs / Events#

5) Ignores / Service settings / Notifications / Settings#

• Starting 2026-03-05, downstream payloads emitted by POST /api/notifications/test use v2 (breaking):
  • legacy type/ts/message fields are removed;
  • new base structure is schema/kind/sentAt/channel/human/debug;
  • Web Push adds title/body as display-oriented top-level fields for service-worker notifications;
  • rendering is capability-aware: Telegram/Email include code blocks, Web Push is natural-language only (no code blocks).

6) GitHub Packages (GHCR) integration#

7) Web Push / Webhooks / Deploy checks#

Supervisor API (default base path /supervisor)#

• GET /supervisor/self-upgrade now includes an optional request object (mode + rollbackOnFailure) while state=running, so the UI can restore which action button is actively running after refresh. The field may be omitted for idle/legacy states.

Request examples#

Trigger all-scope check#

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Forwarded-User: ops' \
  -d '{"scope":"all"}' \
  http://127.0.0.1:50883/api/checks

Trigger update from external webhook#

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Dockrev-Webhook-Secret: change-me' \
  -d '{"action":"update","scope":"stack","stackId":"stk_xxx","targets":[{"serviceId":"svc_web","targetTag":"latest","targetDigest":"sha256:abc123","pullTags":["v1.1.2"]}],"allowArchMismatch":false,"backupMode":"inherit"}' \
  http://127.0.0.1:50883/api/webhooks/trigger

Note: POST /api/webhooks/trigger rejects legacy action=update payloads that omit targets[] with 400 invalid_argument. webhook update also supports scope=service, but you must still provide serviceId and a matching { serviceId, targetTag, targetDigest, pullTags } entry inside targets[].

Read supervisor state#

List jobs with cursor pagination#

GET /api/jobs accepts an opaque cursor, limit (default 100, maximum 200), comma-separated type, status, stackId, and serviceId. Results are stably ordered by createdAt DESC, id DESC and include nextCursor when another page exists. Invalid cursors return 400 invalid_jobs_cursor.

curl -H 'X-Forwarded-User: ops' \
  http://127.0.0.1:50883/supervisor/self-upgrade