Skip to content

Latest commit

 

History

History
861 lines (763 loc) · 50.5 KB

api.md

File metadata and controls

861 lines (763 loc) · 50.5 KB

API Reference

Every route below is registered in backend/cmd/server/main.go, either directly or through a handler's RegisterRoutes method (handlers live under backend/internal/handlers/). All routes are under /api/v1 and require authentication (unless AUTH_DISABLED=true), except /health, /health/ready and /api/v1/version. The web UI is the primary interface; this page exists so a change to a route and a change to this list can be checked against each other mechanically — see scripts/check-api-docs.sh.

:param segments are Gin route parameters (a stack ID, a container ID, and so on), not literal path text. /ws/... routes are WebSocket upgrades, not plain HTTP.

Every WebSocket route limits each incoming frame to 64 KiB. A larger frame closes the connection with code 1009 (message too big) and logs one warning.

Health

Liveness and readiness are separate endpoints, because Capstan is a separate process from Docker. Point restart-on-failure checks at liveness and dependency monitoring at readiness.

  • GET /health — liveness. 200 whenever the process is up and serving. Makes no Docker call, so a Docker daemon restart cannot mark the container unhealthy and get Capstan bounced for an outage restarting it would not fix. This is what the container HEALTHCHECK, and any orchestrator liveness probe, should use.
  • GET /health/ready — readiness. Reports dependencies, 503 when any is degraded, naming which. The Docker probe is bounded by a 2-second timeout so a hung daemon cannot pile up goroutines across repeated probes. Point an uptime monitor, a load balancer, or a Kubernetes readiness probe here.
$ curl -s localhost:5001/health
{"status":"healthy"}

$ curl -s localhost:5001/health/ready          # Docker up
{"checks":{"docker":{"status":"ok"}},"status":"ready"}

$ curl -s localhost:5001/health/ready          # Docker daemon stopped -> HTTP 503
{"checks":{"docker":{"error":"Cannot connect to the Docker daemon at unix:///var/run/docker.sock.",
"status":"unavailable"}},"degraded":["docker"],"status":"degraded"}

Reachability. Loopback reaches both with no configuration, so the container's own healthcheck needs no setup. Every other address is denied by default — upgrading does not silently widen exposure. To let an external monitor in, list its network in HEALTH_ALLOWED_NETWORKS:

HEALTH_ALLOWED_NETWORKS=10.1.0.0/16,192.168.50.7

A denied caller gets 403 with the same error shape as every other refusal:

{"code":"FORBIDDEN","message":"Health endpoint restricted; add this network to HEALTH_ALLOWED_NETWORKS to permit it"}

This is deliberately not TRUSTED_NETWORKS (Gin's trusted-proxy list) or AUTH_DISABLED_ALLOWED_NETWORKS (the AUTH_DISABLED bypass list) — reusing either would mean granting an uptime monitor X-Forwarded-For spoofing or authentication bypass just to let it read a health endpoint.

Version

  • GET /api/v1/version — build identity of the running binary. Public, so an uptime check or a support conversation can answer "what is running here?" without a session.
$ curl -s localhost:5001/api/v1/version
{"version":"0.9.0","commit":"6fb9879...","buildDate":"2026-07-31T09:12:44Z"}

The same values appear on the first startup log line and in the UI under Settings → About. A published image reports the tag it was built under; a local docker build with no --build-arg reports version: dev, which is the honest answer rather than a blank.

Authentication

  • GET /api/v1/auth/status — whether an admin exists yet (drives the first-run setup screen). Public, and deliberately not rate-limited: the frontend polls it on every navigation, and it shares no bucket with /login.

  • POST /api/v1/auth/setup — create the first admin (only when no user exists)

  • POST /api/v1/auth/login — log in

    Both set the session as the HttpOnly capstan_token cookie and return only {user}; the body carries no token. WebSockets authenticate with that cookie.

  • POST /api/v1/auth/logout — log out

  • GET /api/v1/auth/me — current user

  • POST /api/v1/auth/verify-password — re-confirm the current user's password and mint a short-lived unlock token: {ok, unlockToken, expiresIn}. The token is the step-up credential for the secret-reveal endpoints below — send it back as an X-Unlock-Token header. It lasts 5 minutes, is reusable within that window, is bound to the account that minted it, and is revoked on logout. With AUTH_DISABLED there is no password to re-check, so a token is minted unconditionally and the gate is open. See Secret reveal.

  • POST /api/v1/auth/lock — the Lock button: revoke every unlock token of the current user before it expires (204). Open terminal and log streams opened under one close with code 4403 within a few seconds.

  • PUT /api/v1/auth/password — change the current user's password

Every route that checks a password is rate-limited per account and per client IP, on top of the general API budget. setup and login key on the submitted username. verify-password and PUT /auth/password key on the signed-in user and share one budget, separate from login's: 5 attempts per minute per user from one IP, 20 per IP across users, and 60 per user across all IPs. Successful attempts count too. Over budget, the route answers 429 with Retry-After: 60 and {"code":"RATE_LIMITED","message":"..."} before the password is checked.

Settings

  • GET /api/v1/settings/config — effective server configuration (non-secret fields)
  • GET /api/v1/settings/global-env / PUT /api/v1/settings/global-env — read/write the global .env overlay applied across stacks. Gated by X-Unlock-Token — see Secret reveal. Each GET row is {key, value} plus sensitive: true when a locked GET blanks its value (a secret key, or a secret-shaped value such as a private key or a URL with a password, under any key), and readOnly: true for a line a PUT cannot change (a bare KEY, KEY: value, a second variable on its line, or a multi-line value): a changed value for one is refused with 400. A delete is allowed and removes the whole line, so deleting NOTES of NOTES="a" OTHER=b removes OTHER too
  • GET /api/v1/settings/log-retention / PUT /api/v1/settings/log-retention — log retention policy
  • GET /api/v1/settings/updates / PUT /api/v1/settings/updates — update-scan scheduler settings
  • GET /api/v1/settings/git / PUT /api/v1/settings/git — Git integration settings (SSH key, etc.). Also carries the commit author, authorName and authorEmail, which are not credentials. While env values are locked a PUT that sets any field, the author included, is refused with 403 ENV_LOCKED (a locked log masks the author). On PUT an empty or omitted field means "no change"; a non-empty value is trimmed and validated, and anything invalid answers 400 VALIDATION_ERROR with nothing in the request saved: both must be one line, the name at most 200 characters, the email at most 254 characters with exactly one @ and text on both sides. A settings read fault on GET answers 500
  • GET /api/v1/settings/directories / PUT /api/v1/settings/directories — configured stack directories
  • GET /api/v1/settings/scan-depth / PUT /api/v1/settings/scan-depth — directory scan depth
  • GET /api/v1/settings/audit-log — action audit log
  • GET /api/v1/settings/backup / PUT /api/v1/settings/backup — backup engine settings (repository, schedule, retention). On PUT, an rcloneRemote starting with - answers 400 VALIDATION_ERROR "rclone remote must not start with '-'" and nothing in the request is saved (agent-os-tyl6; rclone parsed such a value as a flag). verifyWeekly (boolean, default true when never saved) turns the weekly repository check on or off; see POST /api/v1/backups/verify below

Directories

  • GET /api/v1/directories — list configured directories and their scan state
  • POST /api/v1/directories/scan — trigger a rescan
  • PUT /api/v1/directories/credentials — update stored directory credentials
  • GET /api/v1/directories/credential-status — whether credentials are set, without exposing them
  • PUT /api/v1/directories/push — turn the directory's push switch on or off. Body {"path": "...", "enabled": true|false}; both fields are required, so an omitted enabled is a 400 and false is accepted. An unregistered path answers 404. Returns {"directory": ...} with gitPushEnabled, which every directory carries and which is false until someone with a session turns it on. A rescan that still finds the directory, and a credential save, never change it; if the directory row is deleted (the directory moved away, or its last stack was removed) it comes back false. Each successful change writes one update_directory_push audit-log row (path and new value)

Stacks

Every route that looks a stack up by id answers an unknown id with 404 STACK_NOT_FOUND, and a database that could not answer with 500 INTERNAL_ERROR. That covers the routes below plus GET /api/v1/git* with ?stackId=, GET /api/v1/ws/metrics/:id and POST /api/v1/resources/stacks/:id/update, which answered NOT_FOUND until 2026-09-24, and GET /api/v1/ws/operations/:id/:action, which answered with no code at all until 2026-09-24.

  • GET /api/v1/stacks — list stacks
  • POST /api/v1/stacks — create a stack
  • GET /api/v1/stacks/:id — stack details
  • POST /api/v1/stacks/:id/start — start a stack
  • POST /api/v1/stacks/:id/stop — stop a stack
  • POST /api/v1/stacks/:id/restart — restart a stack
  • POST /api/v1/stacks/:id/pull — pull images for a stack
  • DELETE /api/v1/stacks/:id — delete a stack. When it is the only stack in its folder the whole folder is removed, so a folder holding other files answers 428 STACK_DELETE_COLLATERAL until ?confirmCollateral=true, and a folder holding other registered stacks in subfolders answers 409 STACK_DELETE_NESTED_STACKS, naming them in the message and in details.stacks (id, projectName, directory); delete those first. A stack registered in the same folder through a symlink counts as a sibling: the folder stays, and so does every file a sibling also uses. A registered stack whose folder cannot be resolved blocks the delete with 500, named in the reason and in details.blockingStackId and details.blockingDirectory (agent-os-0s68). When the stack's compose file is gone, compose down cannot run: the project's containers are looked up by their compose label instead. If any remain the delete answers 409 STACK_DELETE_CONTAINERS_REMAIN, naming them in the message and in details.containers (with details.id and details.projectName); run docker compose -p <project> down on the host first. If none remain, compose down is skipped and the stack's row and files are removed, but the project's networks and named volumes are left in place. A lookup that fails answers 500 and keeps the stack (agent-os-epc5).
  • GET /api/v1/stacks/:id/logs — fetch recent logs for a stack
  • GET /api/v1/ws/logs/:id — WebSocket stream of a stack's logs, tailing
  • GET /api/v1/stacks/:id/containers — list a stack's containers with live status

Per-stack operation lock

One operation at a time runs against a stack. A request that would start a second one is refused, never queued, with 409 OPERATION_IN_PROGRESS and the message <kind> in progress since <RFC3339 time>, naming what holds the stack (for example backup in progress since 2026-10-06T09:12:44Z). Retry once it finishes. Until agent-os-a1ye.4 the message repeated the stack id.

Routes that take the lock: start, stop, restart, pull and delete of a stack; GET /api/v1/ws/operations/:id/:action; POST /api/v1/resources/stacks/:id/update and POST /api/v1/resources/containers/:id/update (the latter only for a container belonging to a managed stack); PUT /api/v1/stacks/:id/compose, PUT /api/v1/stacks/:id/compose-env, PUT /api/v1/stacks/:id/env and POST /api/v1/stacks/:id/env; and POST /api/v1/git/pull, with or without ?redeploy=true, which locks every stack whose folder is inside the pulled repository and refuses before pulling anything if one is held (agent-os-88xz). Backups and restores take it too. POST /api/v1/stacks answers 409 DUPLICATE_STACK instead, because losing that race means the name is taken.

An update job holds the lock from the request until the job finishes, including its time in the update queue. Scheduled auto-updates skip a container whose stack is held, leave it pending for the next pass, and report the skip in lastApplyError on GET /api/v1/settings/updates.

Compose & Environment Files

  • GET /api/v1/stacks/:id/compose / PUT /api/v1/stacks/:id/compose — read/write a stack's compose file
  • POST /api/v1/stacks/:id/compose/lint — lint a stack's compose file
  • PUT /api/v1/stacks/:id/compose-env — write a stack's compose file and .env file together, atomically
  • POST /api/v1/compose/lint — lint an arbitrary compose document, not tied to a saved stack (used by the create-stack form)
  • GET /api/v1/stacks/:id/env / PUT /api/v1/stacks/:id/env — read/write a stack's .env file. Gated by X-Unlock-Token — see Secret reveal
  • POST /api/v1/stacks/:id/env — create a stack's .env file

The lint, compose save and create routes need an unlock: see Requests refused while locked.

Secret reveal

A valid session is not enough to read the contents of an env file. The endpoints that serve secrets require a second factor: an unlock token from POST /api/v1/auth/verify-password, sent as an X-Unlock-Token header.

Without a live token:

  • GET /api/v1/stacks/:id/env returns the entry keys, line numbers and comments intact, the value blanked for every key that looks like a secret (*_KEY, *_SECRET, *_PASSWORD, *_TOKEN, *_API_*), no raw field at all, and "locked": true. Non-secret values (e.g. TZ) stay visible.
  • GET /api/v1/settings/global-env blanks secret-looking values the same way and reports "locked": true.
  • PUT on either endpoint returns 403 FORBIDDEN. This is not symmetry for its own sake: a locked caller holds the blanks the GET handed it, and both endpoints replace the whole file, so accepting that write would overwrite every secret it was not allowed to see.

With a live token, all four behave exactly as they did before.

Requests refused while locked

The masking that hides secrets stars any text equal to a secret, including text the same request sent. A locked caller could send a list of guesses and read which one came back as ***. So the requests whose reply passes the caller's own text through that masking are refused without a live token, with 403 ENV_LOCKED and a message that says to unlock (agent-os-ly6i):

  • POST /api/v1/stacks/:id/compose/lint and POST /api/v1/compose/lint
  • PUT /api/v1/stacks/:id/compose and PUT /api/v1/stacks/:id/compose-env, also a compose-only save: a locked GET of the saved file would mask it
  • POST /api/v1/stacks (create)
  • POST /api/v1/stacks/:id/env when the body carries content; an empty create carries no text and is still allowed
  • POST /api/v1/git/commit: a locked log or diff masks the commit message with the stack's secrets (agent-os-xmbg). Push is still allowed

The refusal comes before the lint, the operation lock and any read of the disk, so its body is the same whatever the request held. A locked caller can still read compose files with the secrets masked, and start, stop, restart and pull stacks.

The same 403 ENV_LOCKED refuses the backup requests that would let a locked caller reach secrets or the backups themselves (agent-os-h71i). Pointing the repository at a place the caller controls, then running a backup, would put every stack's .env in the caller's hands:

  • PUT /api/v1/settings/backup when the body sets repository, password, rcloneRemote, rclonePath, any keep* field or autoPrune. A body that only edits the schedule, sync and verify switches, rcloneTransfers or hostname is still saved.
  • POST /api/v1/backups/repo/init, POST /api/v1/backups/restore, POST /api/v1/backups/dr-restore and POST /api/v1/backups/prune
  • PUT and DELETE /api/v1/backups/policies/stack/:stackId: a policy decides which stacks are backed up (agent-os-tp3g). Listing policies stays allowed.

A locked caller can still read the backup settings (the password is never sent; the repository and rclone remote come back with their credentials removed), list snapshots and their file names, read status and history, list stack backup policies, and run a backup, sync or verify against the repository that is already configured.

A locked caller reads GET /api/v1/settings/audit-log without the entries' details (agent-os-3ajm): every entry comes back with detail empty and the reply carries detailsHidden: true. A detail is free text (a commit's file names, an operation's output) that can hold a secret. A search matches the details, so a locked request with one is refused with 403 ENV_LOCKED, whatever it would have matched. The action, date and paging filters still work.

Git

The read routes (status, log, commit diff, /changes, /changes/diff) never download a missing object. In a partial clone (git clone --filter=...) a read that needs an object that was never fetched answers 409 GIT_OBJECT_MISSING instead of fetching it, because that fetch runs the repository's own transport programs (remote.<name>.uploadpack, core.sshCommand, a remote helper). Pull, commit and push still fetch. This needs git 2.45 or later, which the image ships; an older git ignores the setting and fetches (agent-os-taa7).

  • GET /api/v1/git — status; the web UI passes ?stackId=<id>, but the route itself is a plain query-string GET
  • POST /api/v1/git/pull — pull changes. Takes ?stackId=<id> only; a request without it (including the old ?dir=) answers 400 VALIDATION_ERROR "Pull needs a stackId" and pulls nothing (agent-os-hmoy). SSH remotes use the folder's SSH key when its git auth is SSH, else the global key in Settings > Git (git_ssh_key, then GIT_SSH_KEY). The built-in default $HOME/.ssh/id_rsa, when no file is there, means no key: ssh runs as it did before. Host keys are trusted on first use and kept in <DATA_DIR>/known_hosts; a changed host key is refused. Answers 409 GIT_SSH_KEY_UNUSABLE before pulling when the pull URL is SSH and that key is missing, unreadable, readable by other users, or a path ssh would misread (not absolute, or holding ", \, ${ or a control character); the message names the path and the fix. A folder whose git auth is HTTPS has no SSH key, so an SSH pull URL answers 409 GIT_SSH_UNSUPPORTED before any ssh runs, as push does; https and local remotes are unaffected (agent-os-rde7). A pull never fetches or updates submodules, even with submodule.recurse or fetch.recurseSubmodules set, so no submodule URL is contacted, no submodule core.sshCommand runs, and the folder's https token is not sent to a submodule's host (agent-os-1vkh). After a pull that moves a submodule, the folder reads as having uncommitted changes and later pulls answer 400 GIT_DIRTY until git submodule update runs on the host. When a moved submodule pointer is the only change, the refusal names the submodule and says to run git submodule update only if nobody committed inside it on the server; any real change keeps "Working directory has uncommitted changes". The ssh-or-https check reads the remote URL as configured, never the token-masked form (agent-os-0j5h). A pull moves the whole work tree, so it locks every stack of the repository, not only the requested stack's folder, and answers 409 OPERATION_IN_PROGRESS naming the busy stack before pulling anything. The locks are held until the pull, and any redeploy and its verification, finish, so a lifecycle operation on any stack of the repository answers 409 meanwhile. A folder outside any repository answers 404 GIT_NOT_REPO, a folder that no longer exists 404 STACK_DIR_MISSING, and a bare repository 409 GIT_BARE_REPO, all before pulling anything. A registered stack, anywhere, whose folder cannot be resolved refuses the pull, commit and push alike (500, locking cannot tell whether it is inside the repository); the reason names it and its folder, and details.blockingStackId and details.blockingDirectory carry them (agent-os-l4h6). With ?redeploy=true it redeploys only the requested folder's stacks whose compose or env file changed. Every result after a successful diff carries details.siblingStacksChanged, [{stack, name}]: the repository's other stacks whose compose or env file the pull changed, which it does not redeploy. A stack it could not check makes the outcome partial, named in details.siblingCheckFailures ([{stack, reason}]), or details.siblingListError when none could be (agent-os-88xz)
  • GET /api/v1/git/log — commit log. Optional ?file= limits it to commits touching that path. The path must be relative, stay inside the repository after .. is resolved, not start with : (git pathspec magic), contain no NUL and be at most 4096 bytes, else 400 VALIDATION_ERROR "Invalid file path" (agent-os-tyl6; git refused such paths and the route answered 500)
  • GET /api/v1/git/diff/:hash — commit diff. :hash must be 7–64 lowercase hex characters, else 400 VALIDATION_ERROR "Invalid commit hash format" (the 64 upper bound is agent-os-tyl6; longer values answered 500). A well-formed hash that names no commit (unknown, or an object that is not a commit) answers 404 NOT_FOUND "Commit not found"; it answered 500 before 2026-09-24 (agent-os-tyl6). A missing object in a partial clone answers 409 GIT_OBJECT_MISSING. Other git failures stay 500. Answers {commit, diff, files, hiddenFiles}. files lists every path the commit touched against every parent. Env files are never shown: an env-like name or folder, a stack's env file, a file a compose file names in env_file: or secrets: file: (following include: and extends: file:, in today's compose files and in every compose file of that commit and its parents), or the target of an env-named symlink. Their paths are in hiddenFiles and their contents are left out of diff by git itself (agent-os-2omy). If the stack list can't be read, it answers 500 rather than an unchecked diff

Commit and push

Nothing commits or pushes on its own: saving a file never touches git. These three routes take a stack by stackId only (no dir fallback). One repository can hold several stack folders; the change list and the push switch are this stack's folder's, the lock covers every stack in the repository, and a push sends the whole branch, including commits made outside Capstan. Refusals are 4xx or 502, never 401. Commit and push results are action results (outcome, reason, details) with the error code in details.code.

  • GET /api/v1/git/changes — ?stackId=<id>. The tracked files with uncommitted changes in the stack's folder: {branch, detached, trackingBranch, hasUpstream, ahead, behind, pushEnabled, identityConfigured, changes}, each change {path, origPath?, status, isEnv}. path is relative to the repository top level and is the value a commit request names. status is git's porcelain v2 code (.M modified, M. staged, R. renamed). hasUpstream comes from @{upstream} alone; ahead/behind can be counted against origin/<branch> when none is set. Untracked files are not listed. isEnv marks a file whose name, ignoring case, is env or .env, starts with .env (.envrc, .env-prod, .env.prod), ends with .env or contains .env.; the stack's own env file; every env_file: entry (string, list or {path:} form) of the compose file of each stack in the folder; and a file that an env-named path resolves to through a symlink (tracked anywhere in the repository, or untracked, ignored included, in the folder). When a compose file cannot be read or parsed, or names an env_file: it cannot resolve (an interpolated ${...} path), every changed file of the folder but the compose files is isEnv. Not seen: an env file copied to an unrelated name, and one moved and changed past git's rename detection. A push switch or author setting that cannot be read is a 500, never false. Unresolved conflicts in the folder answer 409 GIT_OPERATION_IN_PROGRESS
  • GET /api/v1/git/changes/diff — ?stackId=<id>&path=<path>. Read-only, no lock. The uncommitted diff of one file from /changes against HEAD: {path, hidden, diff}, diff a raw unified diff with a//b/ prefixes and no colour (a rename holds both paths). An env file (isEnv in the change list, which covers a rename from an env name) answers 200 {hidden: true, diff: ""} and its contents are never read or sent. The repository's external diff, diff driver and textconv commands do not run, and a submodule shows only its commit line (--submodule=short): its files' contents are not shown and its own external diff and textconv commands do not run; clean and process filters still run, as for git status. Answers 400 VALIDATION_ERROR when path is missing or not in the change list, and the errors /changes answers (a repository with no commits yet included)
  • POST /api/v1/git/commit — body {stackId, message, files, confirmEnv, push}. Commits exactly files (paths as /changes lists them; a rename commits its old path too) with literal pathspecs, as the author in Settings > Git. No repository hook, fsmonitor program or commit signing runs during the request. The audit row's file count is the paths committed. With push: true it then pushes as POST /git/push does, under the same lock. Answers:
    • 400 VALIDATION_ERROR: blank message, no files, or a file that is not a changed tracked file of this stack's folder (including a sibling folder's)
    • 400 GIT_ENV_CONFIRM_REQUIRED: an env file without confirmEnv: true
    • 400 GIT_IDENTITY_MISSING: author name or email unset
    • 403 GIT_PUSH_DISABLED: the folder's push switch is off (it gates commit too)
    • 409 GIT_DETACHED_HEAD, GIT_OPERATION_IN_PROGRESS (merge, cherry-pick or revert underway, or another git process holds the index), OPERATION_IN_PROGRESS (a stack in the repository is busy)
    • with push: true, every push refusal below that can be predicted is checked before the commit, so nothing is written
    • 207 partial: the commit landed and the push failed; details.commit, details.pushCode, details.pushReason. The commit is kept
    • each commit writes one git_commit audit row (path, commit, file count)
  • POST /api/v1/git/push — body {stackId}. Pushes the current branch to its upstream (branch.<b>.remote, HEAD:<branch.<b>.merge>): no force, no tags, no submodules, no new upstream, hooks off. 200 success with details.range, or no_change when the remote already has it. Answers:
    • 403 GIT_PUSH_DISABLED, checked first
    • 409 GIT_SSH_UNSUPPORTED: the push URL is SSH-shaped (ssh://, git+ssh://, ssh+git://, user@host:path, host:path) and no SSH key applies: the folder's git auth is HTTPS, or it inherits and no global key is configured (see POST /git/pull for which key applies)
    • 409 GIT_SSH_KEY_UNUSABLE: the push URL is SSH-shaped and the key that applies is missing, unreadable, readable by other users, or a path ssh would misread; the message names the path and the fix
    • 409 GIT_PUSH_URL_UNSUPPORTED: git://, another scheme, or a <transport>:: helper; more than one push URL (Capstan pushes to exactly one); or a remote whose name is a URL. Allowed: https://, http://, file://, a local path, and SSH with a usable key
    • 409 GIT_DETACHED_HEAD; 409 GIT_NO_UPSTREAM (no upstream, one in the same repository (remote .), or more than one branch.<b>.remote or branch.<b>.merge value)
    • 409 GIT_REMOTE_AHEAD: the remote has commits this branch lacks; pull first
    • 409 GIT_PUSH_REJECTED: the remote refused for another reason
    • 502 GIT_REMOTE_UNREACHABLE: unreachable, or the credentials were refused. git's own (redacted) message for any failed push is logged at WARN as "git push failed"; it is the only place the two causes differ
    • each push that runs writes one git_push audit row (path, remote name, branch, outcome); the remote URL is never recorded

Monitoring & Dashboard

  • GET /api/v1/dashboard/stats — aggregate counts (stacks, containers, images, volumes, networks) for the dashboard landing page
  • GET /api/v1/ws/dashboard/metrics — WebSocket stream of dashboard metrics
  • GET /api/v1/ws/metrics/:id — WebSocket stream of a single container's resource metrics
  • GET /api/v1/ws/events — WebSocket stream of Docker events

Resources

Direct Docker resource management, independent of any stack.

  • GET /api/v1/resources/images — list images
  • DELETE /api/v1/resources/images/:id — delete an image
  • POST /api/v1/resources/images/prune — prune unused images
  • GET /api/v1/resources/images/prune-impact — the stacks whose images an image prune with all=true would remove, in the volume prune-impact shape below. Docker's prune removes every image no container uses, stopped ones included, so a stopped or removed stack's images go too. A stack owns an image by its compose project label or names it in its compose file (a built service's default name counts); an image whose containers Docker did not count is listed too. Dangling images are not listed: the default prune removes them anyway. Same error rules as the volume route
  • GET /api/v1/resources/containers — list containers
  • GET /api/v1/resources/containers/:id/inspect — full inspect output for a container
  • POST /api/v1/resources/containers/:id/start — start a container
  • POST /api/v1/resources/containers/:id/stop — stop a container
  • POST /api/v1/resources/containers/:id/restart — restart a container
  • DELETE /api/v1/resources/containers/:id — delete a container
  • POST /api/v1/resources/containers/prune — prune stopped containers
  • GET /api/v1/resources/containers/prune-impact — the stacks whose stopped (exited, created or dead) containers a container prune would remove, in the volume prune-impact shape below. The until filter is not applied, so the list can only be longer. Same error rules as the volume route
  • GET /api/v1/resources/updates — check for available image updates
  • POST /api/v1/resources/containers/:id/update — update a single container to its latest image
  • POST /api/v1/resources/stacks/:id/update — update every container in a stack to its latest image
  • GET /api/v1/resources/updates/jobs — list running/recent update jobs
  • GET /api/v1/resources/updates/jobs/:jobId — a single update job's status
  • GET /api/v1/resources/updates/history — update history. limit defaults to 25 and is capped at 100; the response's limit is the applied value
  • DELETE /api/v1/resources/updates/history — clear update history
  • GET /api/v1/resources/auto-update/policies — list auto-update policies
  • PUT /api/v1/resources/auto-update/policies/:targetType/:targetId — create/update an auto-update policy for a container or stack. For targetType container, targetId is the container's name without the leading /, not its ID: an update recreates the container under a new ID, and the name is what survives. A policy saved earlier under a full 64-character lowercase container ID is moved to that container's name by the update scheduler, which runs only while update scanning is on. If the name already has a policy, that policy is kept and the ID-keyed one is deleted; a policy whose container name cannot be found stays as it was.
  • DELETE /api/v1/resources/auto-update/policies/:targetType/:targetId — remove an auto-update policy
  • GET /api/v1/resources/volumes — list volumes
  • DELETE /api/v1/resources/volumes/:name — delete a volume
  • POST /api/v1/resources/volumes/prune — prune unused volumes
  • GET /api/v1/resources/volumes/prune-impact — the stacks whose volumes a volume prune with all=true would remove: {stacks: [{stack, items}], uncheckedStacks}. Docker's prune removes every volume no container holds, which includes a removed (down) stack's named and external volumes. A stack owns a volume by its compose project label or names it in its compose file; a volume whose usage Docker did not report is listed too. uncheckedStacks names stacks whose compose file could not be read. 503 when Docker is unavailable and 500 on another read failure, never an empty answer
  • GET /api/v1/resources/volumes/prune-scope — {removesAllUnused}: true when a volume prune without all=true removes every unused volume, named ones included. Docker does that for a request below API 1.42 (an Engine older than 23, or DOCKER_API_VERSION pinned below 1.42). 503 when Docker is unavailable and 500 when the version could not be read, never false
  • GET /api/v1/resources/networks — list networks
  • POST /api/v1/resources/networks — create a network
  • DELETE /api/v1/resources/networks/:id — delete a network
  • POST /api/v1/resources/networks/prune — prune unused networks
  • GET /api/v1/resources/networks/prune-impact — the same answer for a network prune, which removes every network no running container is attached to: a stopped stack's networks as well as a removed one's, external networks included. The until filter is not applied, so the list can only be longer than what the prune removes
  • GET /api/v1/resources/build-cache — inspect Docker build cache usage
  • POST /api/v1/resources/build-cache/prune — prune the build cache
  • GET /api/v1/resources/host/summary — per-category counts and sizes of what Docker keeps on disk, and what can be freed. disk.reclaimable is what the Free-up-space defaults remove (unused images, build cache, stopped containers outside any compose project); disk.reclaimableAll adds unattached volumes. Served from a snapshot up to 30 s old (measuredAt). Nothing a stack uses or owns is counted as reclaimable, whether the stack is running or not. 503 when Docker is unavailable, never a zeroed body
  • GET /api/v1/resources/host/candidates — the items behind those figures: images, containers, volumes and networks as {id, label, size?, detail?} lists, and build cache as {count, bytes}. Read fresh on every call. size is omitted when Docker did not report it. Removes nothing
  • POST /api/v1/resources/host/free-space — remove the listed items, body {images?, containers?, volumes?, networks?: string[], buildCache?: bool} (IDs as candidates returns them, at most 1000 per category). Waits for no stack: it answers 409 OPERATION_IN_PROGRESS while any stack operation runs, and blocks stack operations while it runs. The candidates are read again first, and a requested ID that is no longer one (in use, owned by a stack, or gone) is skipped, never removed. Nothing is forced. Returns an action result whose details has {removed, failed: [{id, reason}], skipped: [{id, reason}]} per category, buildCache: {requested, removed, spaceReclaimed, failed?, skipped?}, and spaceReclaimed, Docker's disk use before minus after (omitted when it could not be measured). Outcome success, partial (207), no_change, or failed (500) when every removal failed. 400 VALIDATION_ERROR for an empty request, too many IDs, or an ID that is not a Docker ID or name. Carries on if the browser disconnects (15 min limit)
  • GET /api/v1/resources/cleanup/policy — the scheduled Docker cleanup policy, plus the server-enforced minimum image age the API will accept. categories holds one switch per category (danglingImages, unusedImages, buildCache, containers, volumes, networks); with no stored value, dangling images and build cache are on and the rest off. alertThresholdBytes is the dashboard alert threshold (default 5 GiB, 0 = off). nextRunAt (RFC3339) is the next scheduled run, present only while cleanup is enabled and scheduled
  • PUT /api/v1/resources/cleanup/policy — enable or disable scheduled cleanup and set its interval, minimum image age, categories and alert threshold. Every field is optional; categories may be partial, and a switch it leaves out keeps its stored value. A minimum age below the server floor is rejected, not clamped: a prune is irreversible, so an operator who asked for 0 must not be told 1 was stored. alertThresholdBytes must be between 0 and 1 TiB. An enabled policy with every category off is rejected with 400 "Turn on at least one category, or turn automatic cleanup off". Everything is validated before anything is stored, and the changed keys are stored together
  • POST /api/v1/resources/cleanup/preview — what a cleanup would remove. Removes nothing
  • POST /api/v1/resources/cleanup/run — run a cleanup now, independently of the schedule and whether the schedule is enabled. It removes the categories the policy has switched on. Today a run removes dangling images and build cache only; the other categories are stored but not yet acted on
  • GET /api/v1/resources/cleanup/history — recent cleanup runs. limit defaults to 50 and is capped at 100. Each run records the categories it acted on (comma-separated), per-category counts (containersDeleted, volumesDeleted, networksDeleted) and otherBytesReclaimed. status is success or failed; skipped is reserved for a scheduled run that finds another operation holding its turn, which no run writes yet

Terminal

  • GET /api/v1/ws/terminal/:id/:container — WebSocket PTY session docker exec'd into a running container. Capped at 5 concurrent sessions (backend/internal/handlers/terminal.go) — materially more expensive than a log or metrics stream.

Operations

  • GET /api/v1/ws/operations/:id/:action — WebSocket stream of a long-running stack operation's progress (start/stop/restart/pull). Refused before the upgrade with an AppError body: 404 STACK_NOT_FOUND for an unknown stack, 409 OPERATION_IN_PROGRESS while another operation holds the stack, 400 VALIDATION_ERROR for an unknown action, 503 DOCKER_UNAVAILABLE when the daemon was unreachable at startup

Update Jobs (WebSocket)

  • GET /api/v1/ws/updates/jobs/:jobId — WebSocket stream of a single update job's progress, companion to the polling GET /api/v1/resources/updates/jobs/:jobId above

Backups

  • GET /api/v1/backups/policies — list backup policies
  • PUT /api/v1/backups/policies/stack/:stackId — create/update a stack's backup policy
  • DELETE /api/v1/backups/policies/stack/:stackId — remove a stack's backup policy
  • GET /api/v1/backups/status — current backup engine availability and state
  • GET /api/v1/backups/history — run history
  • GET /api/v1/backups/runs/:runId — a single run's detail
  • GET /api/v1/backups/snapshots — list restic snapshots
  • GET /api/v1/backups/snapshots/:snapshotId/preview — preview a snapshot's contents before restoring
  • POST /api/v1/backups/run — start a backup run
  • GET /api/v1/backups/sync/preflight — count the remote files a sync would delete now and the per-run cap ({remoteOnly, cap})
  • POST /api/v1/backups/sync — sync to the configured cloud remote; optional body {allowDeleteCount} lets this one run delete up to that many remote files when the pre-flight count is above the cap
  • POST /api/v1/backups/restore — restore a stack from a snapshot
  • POST /api/v1/backups/dr-restore — disaster-recovery restore (whole instance, onto a fresh host)
  • POST /api/v1/backups/prune — apply retention and prune old snapshots
  • POST /api/v1/backups/verify — verify repository integrity by reading pack data (readDataSubset defaults to 5%; 100% reads every pack). Answers 409 BACKUP_BUSY while a backup, sync, restore, prune or another check runs: restic check locks the repository exclusively, so the two cannot overlap. A check that loses that race after the 202 is recorded as skipped, never failed. With verifyWeekly on, the scheduler also runs one check (trigger scheduled, default subset) at the end of a scheduled backup cycle when no check ended in success or failed in the last 7 days; a scheduled backup that falls due while it runs is recorded as skipped. A failed check is reported on lastVerify and never stops later backups
  • POST /api/v1/backups/repo/init — initialize the restic repository
  • POST /api/v1/backups/cloud/test — test the configured cloud remote's connectivity/credentials
  • GET /api/v1/ws/backups/run/:runId — WebSocket stream of a backup run's progress
  • GET /api/v1/ws/backups/sync/:runId — WebSocket stream of a sync run's progress
  • GET /api/v1/ws/backups/restore/:runId — WebSocket stream of a restore run's progress
  • GET /api/v1/ws/backups/dr-restore/:runId — WebSocket stream of a DR-restore run's progress
  • GET /api/v1/ws/backups/prune/:runId — WebSocket stream of a prune run's progress
  • GET /api/v1/ws/backups/verify/:runId — WebSocket stream of a repository verification run's progress

Backup error codes

This page listed routes and no error codes at all until 2026-09-15. It gains this section rather than a line in the Backups list because the backup handlers are the ones whose failures a client must TELL APART: several distinct faults share a status, and the recoveries for them are mutually exclusive. A client branches on code, and on details.repoState where one is present — never on the status alone.

Every error body is {"code", "message", "details"?}. message is a sentence computed server-side naming the cause that actually holds; it is not a fixed string per code and should be surfaced, not replaced.

code status details means recovery
BACKUP_UNAVAILABLE 409 cause (always) the engine binary is missing — restic, or rclone for the cloud paths. No repository was contacted, so nothing is claimed about it install/restore the binary; this is a deployment fault, not a settings one
BACKUP_REPO_UNINITIALIZED 409 repoState: "uninitialized" no repository exists at the configured location initialise the repository (POST /api/v1/backups/repo/init)
BACKUP_REPO_UNREACHABLE 503 repoState a repository is configured but this request could not read it. repoState says which of four causes holds depends on repoState, below
BACKUP_BUSY 409 — another backup operation holds the lock retry once it finishes

details.cause under BACKUP_UNAVAILABLE is "restic_missing" or "rclone_missing". It is derived from the same availability value that produced message, so the two can never name different binaries — which matters in the one case that surprises: when BOTH binaries are absent, the cloud endpoints report restic_missing, not rclone_missing, even though their own guard is about rclone. Availability resolves restic first and stops there, so restic is the fault to fix first and it is the one both fields name.

details.repoState under BACKUP_REPO_UNREACHABLE, and the reason the four are not interchangeable:

repoState means recovery
password_missing no restic password is configured, so the repository was never contacted. This is the DEFAULT state of a new install: both shipped compose files leave RESTIC_PASSWORD commented out set the restic password in Backup settings. Do NOT go looking at the remote or the mount
wrong_password a password is configured and the repository rejected it (restic exit 12). The repository is reachable and holds its snapshots correct the password. Do NOT initialise over it
unreachable the repository could not be read for some other reason — network, permissions, a missing mount. It may well exist and hold every backup check the remote or the mount
settings_unreadable the backup settings could not be read, so WHICH repository is configured is itself unknown repair the settings/database

GET /api/v1/backups/status and GET /api/v1/settings/backup carry the same repoState on a 200, alongside repoStateMessage. Both also use "ok", and "" for "not probed" — which ships when restic is absent, since the probe returns before running. repoStateMessage is empty whenever repoState is "ok".

Wire contract change, 2026-09-15

GET /api/v1/backups/snapshots previously answered 200 with an empty array when the restic binary was absent. It now answers 409 BACKUP_UNAVAILABLE. A client that treated the empty array as "this stack has no backups" was being told a fault was a benign state, which is why this changed; a client that still reads 200 [] that way remains correct, because the empty array now means only what it says.

The same endpoint previously answered 500 "Failed to list snapshots" for a repository that had never been initialised — restic exits 10 on the listing path just as it does on the probe — and now answers 409 BACKUP_REPO_UNINITIALIZED. GET /api/v1/backups/snapshots/:snapshotId/preview answered that same state with 404, and now answers the same 409, so one state has one shape.

Folding the repository state into 409 did not by itself leave 404 free to mean "unknown snapshot id": it was the endpoint's only 404, and for a while a well-formed id naming no snapshot reached restic and answered 500 INTERNAL_ERROR. Since 2026-09-24 that case answers 404 NOT_FOUND (agent-os-uh8y), below.

GET /api/v1/backups/snapshots/:snapshotId/preview

The complete set of shapes:

status code when
200 — {"entries": [...]}, the snapshot's file listing
400 VALIDATION_ERROR the id is not 8–64 hex characters or latest. restic is not called
409 BACKUP_UNAVAILABLE the restic binary is missing
503 BACKUP_REPO_UNREACHABLE the repository could not be read; details.repoState says why
409 BACKUP_REPO_UNINITIALIZED no repository exists yet
404 NOT_FOUND the repository lists fine and no snapshot's id starts with the given id (case-insensitive), or the id is latest and the repository holds no snapshots. message names the id
500 INTERNAL_ERROR any other preview failure, including a preview that failed for a snapshot the repository does list, and a failure where the repository could not be listed to check

How the 404 is decided: restic has no exit code for "snapshot not found". With restic 0.18.0, restic ls exits 1 for an unknown id prefix, an unknown full-length id and latest on an empty repository, and 1 is also its generic fatal exit; the message for a full-length id comes from the storage backend and differs between backends. So when a preview fails, the server lists the repository's snapshots and answers 404 only if that listing succeeds and names no matching snapshot. A successful preview costs no extra restic call.

Why 404 and not 409: the missing thing is the snapshot, which is the resource the URL names. The earlier reason to avoid 404 here, that the web UI's classifyError replaced the server's message on 404, no longer holds; since agent-os-mc4i it shows the server's message on 404 as it does on 409.

GET /api/v1/backups/snapshots?stackId=

stackId filters the listing by restic tag. Empty or absent means no filter: every snapshot in the repository. A non-empty value must match the stack-ID charset (letters, digits, space, ., _, :, ~, -) and be at most 1024 bytes, or the endpoint answers 400 VALIDATION_ERROR "Invalid stack ID" before restic is called (agent-os-qh3g). Before 2026-09-24 the value went to restic unchecked: a comma silently turned the filter into an AND of two tags, and a value past Linux's argument-length limit answered 500.

A well-formed stackId is NOT checked against the stacks table. An ID with no matching snapshots, including one for a stack that has since been deleted, answers 200 []. That is deliberate: deleting a stack does not delete its snapshots, and a stack whose ID changed keeps its older snapshots under the old ID, so an ID with no stack behind it can still name real backups.

POST /api/v1/backups/restore

snapshotId must be 8–64 hex characters or latest (the same rule as the preview route), or the endpoint answers 400 VALIDATION_ERROR "Invalid snapshot ID" before a run starts (agent-os-tyl6). Before 2026-09-24 a malformed id answered 202, took the backup lock and left a failed run in the history. It never reached restic restore: the run only restores an id that restic lists for the stack, and still fails for a well-formed id it does not list.

A restore always goes into the stack's own directory. It deletes files that are not in the snapshot, except mounted filesystems and CACHEDIR.TAG directories, which backups never include (see Restoring a backup). If part of the directory cannot be read for that check, the run fails with "restore refused" before the stack is stopped.

The request has no target field. A request that sends a non-empty target answers 400 VALIDATION_ERROR ("The target parameter was removed") and starts no run (agent-os-z91e.48). Before 2026-10-07 it restored the whole stack's snapshot into a subdirectory of the stack, merged with what was there, and deleted nothing.

Keeping this page honest

scripts/check-api-docs.sh extracts every group.METHOD("path", ...) call from backend/internal/handlers/*.go and fails CI if a registered route is missing from this page (or from that script's own allowlist). If you add, rename, or remove a route, either update this page or explain the omission in the script's ROUTE_ALLOW table.

Not covered here on purpose: /assets/*, /fonts/* and /vite.svg (static file serving, not API endpoints) and the SPA fallback that serves index.html for any unmatched non-/api/ path. None of these are .GET/.POST/etc. calls, so the coverage script does not extract them either — there is nothing to allowlist.

Out of scope for this page: a full OpenAPI/Swagger specification (e.g. via swaggo annotations or huma). This route list plus the coverage script catches drift at a fraction of the cost; a generated spec with request/response schemas would be a reasonable follow-up if the API grows a public/external consumer beyond the bundled web UI.


← Documentation index