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.
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 containerHEALTHCHECK, 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.7A 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.
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.
-
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 inBoth set the session as the HttpOnly
capstan_tokencookie 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 anX-Unlock-Tokenheader. It lasts 5 minutes, is reusable within that window, is bound to the account that minted it, and is revoked on logout. WithAUTH_DISABLEDthere 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.
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.envoverlay applied across stacks. Gated byX-Unlock-Token— see Secret reveal. EachGETrow is{key, value}plussensitive: truewhen a lockedGETblanks its value (a secret key, or a secret-shaped value such as a private key or a URL with a password, under any key), andreadOnly: truefor a line aPUTcannot change (a bareKEY,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 deletingNOTESofNOTES="a" OTHER=bremovesOTHERtooGET /api/v1/settings/log-retention/PUT /api/v1/settings/log-retention— log retention policyGET /api/v1/settings/updates/PUT /api/v1/settings/updates— update-scan scheduler settingsGET /api/v1/settings/git/PUT /api/v1/settings/git— Git integration settings (SSH key, etc.). Also carries the commit author,authorNameandauthorEmail, which are not credentials. While env values are locked a PUT that sets any field, the author included, is refused with 403ENV_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 400VALIDATION_ERRORwith 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 500GET /api/v1/settings/directories/PUT /api/v1/settings/directories— configured stack directoriesGET /api/v1/settings/scan-depth/PUT /api/v1/settings/scan-depth— directory scan depthGET /api/v1/settings/audit-log— action audit logGET /api/v1/settings/backup/PUT /api/v1/settings/backup— backup engine settings (repository, schedule, retention). On PUT, anrcloneRemotestarting with-answers 400VALIDATION_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, defaulttruewhen never saved) turns the weekly repository check on or off; seePOST /api/v1/backups/verifybelow
GET /api/v1/directories— list configured directories and their scan statePOST /api/v1/directories/scan— trigger a rescanPUT /api/v1/directories/credentials— update stored directory credentialsGET /api/v1/directories/credential-status— whether credentials are set, without exposing themPUT /api/v1/directories/push— turn the directory's push switch on or off. Body{"path": "...", "enabled": true|false}; both fields are required, so an omittedenabledis a 400 andfalseis accepted. An unregistered path answers 404. Returns{"directory": ...}withgitPushEnabled, which every directory carries and which isfalseuntil 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 backfalse. Each successful change writes oneupdate_directory_pushaudit-log row (path and new value)
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 stacksPOST /api/v1/stacks— create a stackGET /api/v1/stacks/:id— stack detailsPOST /api/v1/stacks/:id/start— start a stackPOST /api/v1/stacks/:id/stop— stop a stackPOST /api/v1/stacks/:id/restart— restart a stackPOST /api/v1/stacks/:id/pull— pull images for a stackDELETE /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 428STACK_DELETE_COLLATERALuntil?confirmCollateral=true, and a folder holding other registered stacks in subfolders answers 409STACK_DELETE_NESTED_STACKS, naming them in the message and indetails.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 indetails.blockingStackIdanddetails.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 409STACK_DELETE_CONTAINERS_REMAIN, naming them in the message and indetails.containers(withdetails.idanddetails.projectName); rundocker compose -p <project> downon 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 stackGET /api/v1/ws/logs/:id— WebSocket stream of a stack's logs, tailingGET /api/v1/stacks/:id/containers— list a stack's containers with live status
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.
GET /api/v1/stacks/:id/compose/PUT /api/v1/stacks/:id/compose— read/write a stack's compose filePOST /api/v1/stacks/:id/compose/lint— lint a stack's compose filePUT /api/v1/stacks/:id/compose-env— write a stack's compose file and.envfile together, atomicallyPOST /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.envfile. Gated byX-Unlock-Token— see Secret revealPOST /api/v1/stacks/:id/env— create a stack's.envfile
The lint, compose save and create routes need an unlock: see Requests refused while locked.
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/envreturns the entry keys, line numbers and comments intact, the value blanked for every key that looks like a secret (*_KEY,*_SECRET,*_PASSWORD,*_TOKEN,*_API_*), norawfield at all, and"locked": true. Non-secret values (e.g.TZ) stay visible.GET /api/v1/settings/global-envblanks secret-looking values the same way and reports"locked": true.PUTon either endpoint returns 403FORBIDDEN. This is not symmetry for its own sake: a locked caller holds the blanks theGEThanded 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.
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/lintandPOST /api/v1/compose/lintPUT /api/v1/stacks/:id/composeandPUT /api/v1/stacks/:id/compose-env, also a compose-only save: a lockedGETof the saved file would mask itPOST /api/v1/stacks(create)POST /api/v1/stacks/:id/envwhen the body carries content; an empty create carries no text and is still allowedPOST /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/backupwhen the body setsrepository,password,rcloneRemote,rclonePath, anykeep*field orautoPrune. A body that only edits the schedule, sync and verify switches,rcloneTransfersorhostnameis still saved.POST /api/v1/backups/repo/init,POST /api/v1/backups/restore,POST /api/v1/backups/dr-restoreandPOST /api/v1/backups/prunePUTandDELETE /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.
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 GETPOST /api/v1/git/pull— pull changes. Takes?stackId=<id>only; a request without it (including the old?dir=) answers 400VALIDATION_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, thenGIT_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 409GIT_SSH_KEY_UNUSABLEbefore 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 409GIT_SSH_UNSUPPORTEDbefore any ssh runs, as push does; https and local remotes are unaffected (agent-os-rde7). A pull never fetches or updates submodules, even withsubmodule.recurseorfetch.recurseSubmodulesset, so no submodule URL is contacted, no submodulecore.sshCommandruns, 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 400GIT_DIRTYuntilgit submodule updateruns on the host. When a moved submodule pointer is the only change, the refusal names the submodule and says to rungit submodule updateonly 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 409OPERATION_IN_PROGRESSnaming 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 404GIT_NOT_REPO, a folder that no longer exists 404STACK_DIR_MISSING, and a bare repository 409GIT_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, anddetails.blockingStackIdanddetails.blockingDirectorycarry them (agent-os-l4h6). With?redeploy=trueit redeploys only the requested folder's stacks whose compose or env file changed. Every result after a successful diff carriesdetails.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 outcomepartial, named indetails.siblingCheckFailures([{stack, reason}]), ordetails.siblingListErrorwhen 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 400VALIDATION_ERROR"Invalid file path" (agent-os-tyl6; git refused such paths and the route answered 500)GET /api/v1/git/diff/:hash— commit diff.:hashmust be 7–64 lowercase hex characters, else 400VALIDATION_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 404NOT_FOUND"Commit not found"; it answered 500 before 2026-09-24 (agent-os-tyl6). A missing object in a partial clone answers 409GIT_OBJECT_MISSING. Other git failures stay 500. Answers{commit, diff, files, hiddenFiles}.fileslists 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 inenv_file:orsecrets: file:(followinginclude:andextends: 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 inhiddenFilesand their contents are left out ofdiffby git itself (agent-os-2omy). If the stack list can't be read, it answers 500 rather than an unchecked diff
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}.pathis relative to the repository top level and is the value a commit request names.statusis git's porcelain v2 code (.Mmodified,M.staged,R.renamed).hasUpstreamcomes from@{upstream}alone;ahead/behindcan be counted againstorigin/<branch>when none is set. Untracked files are not listed.isEnvmarks a file whose name, ignoring case, isenvor.env, starts with.env(.envrc,.env-prod,.env.prod), ends with.envor contains.env.; the stack's own env file; everyenv_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 anenv_file:it cannot resolve (an interpolated${...}path), every changed file of the folder but the compose files isisEnv. 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, neverfalse. Unresolved conflicts in the folder answer 409GIT_OPERATION_IN_PROGRESSGET /api/v1/git/changes/diff—?stackId=<id>&path=<path>. Read-only, no lock. The uncommitted diff of one file from/changesagainstHEAD:{path, hidden, diff},diffa raw unified diff witha//b/prefixes and no colour (a rename holds both paths). An env file (isEnvin 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 forgit status. Answers 400VALIDATION_ERRORwhenpathis missing or not in the change list, and the errors/changesanswers (a repository with no commits yet included)POST /api/v1/git/commit— body{stackId, message, files, confirmEnv, push}. Commits exactlyfiles(paths as/changeslists 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. Withpush: trueit then pushes asPOST /git/pushdoes, 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 withoutconfirmEnv: 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_commitaudit row (path, commit, file count)
- 400
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. 200successwithdetails.range, orno_changewhen 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 (seePOST /git/pullfor 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; 409GIT_NO_UPSTREAM(no upstream, one in the same repository (remote.), or more than onebranch.<b>.remoteorbranch.<b>.mergevalue) - 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_pushaudit row (path, remote name, branch, outcome); the remote URL is never recorded
- 403
GET /api/v1/dashboard/stats— aggregate counts (stacks, containers, images, volumes, networks) for the dashboard landing pageGET /api/v1/ws/dashboard/metrics— WebSocket stream of dashboard metricsGET /api/v1/ws/metrics/:id— WebSocket stream of a single container's resource metricsGET /api/v1/ws/events— WebSocket stream of Docker events
Direct Docker resource management, independent of any stack.
GET /api/v1/resources/images— list imagesDELETE /api/v1/resources/images/:id— delete an imagePOST /api/v1/resources/images/prune— prune unused imagesGET /api/v1/resources/images/prune-impact— the stacks whose images an image prune withall=truewould 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 routeGET /api/v1/resources/containers— list containersGET /api/v1/resources/containers/:id/inspect— full inspect output for a containerPOST /api/v1/resources/containers/:id/start— start a containerPOST /api/v1/resources/containers/:id/stop— stop a containerPOST /api/v1/resources/containers/:id/restart— restart a containerDELETE /api/v1/resources/containers/:id— delete a containerPOST /api/v1/resources/containers/prune— prune stopped containersGET /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. Theuntilfilter is not applied, so the list can only be longer. Same error rules as the volume routeGET /api/v1/resources/updates— check for available image updatesPOST /api/v1/resources/containers/:id/update— update a single container to its latest imagePOST /api/v1/resources/stacks/:id/update— update every container in a stack to its latest imageGET /api/v1/resources/updates/jobs— list running/recent update jobsGET /api/v1/resources/updates/jobs/:jobId— a single update job's statusGET /api/v1/resources/updates/history— update history.limitdefaults to 25 and is capped at 100; the response'slimitis the applied valueDELETE /api/v1/resources/updates/history— clear update historyGET /api/v1/resources/auto-update/policies— list auto-update policiesPUT /api/v1/resources/auto-update/policies/:targetType/:targetId— create/update an auto-update policy for a container or stack. FortargetTypecontainer,targetIdis 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 policyGET /api/v1/resources/volumes— list volumesDELETE /api/v1/resources/volumes/:name— delete a volumePOST /api/v1/resources/volumes/prune— prune unused volumesGET /api/v1/resources/volumes/prune-impact— the stacks whose volumes a volume prune withall=truewould 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.uncheckedStacksnames stacks whose compose file could not be read. 503 when Docker is unavailable and 500 on another read failure, never an empty answerGET /api/v1/resources/volumes/prune-scope—{removesAllUnused}: true when a volume prune withoutall=trueremoves every unused volume, named ones included. Docker does that for a request below API 1.42 (an Engine older than 23, orDOCKER_API_VERSIONpinned below 1.42). 503 when Docker is unavailable and 500 when the version could not be read, neverfalseGET /api/v1/resources/networks— list networksPOST /api/v1/resources/networks— create a networkDELETE /api/v1/resources/networks/:id— delete a networkPOST /api/v1/resources/networks/prune— prune unused networksGET /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. Theuntilfilter is not applied, so the list can only be longer than what the prune removesGET /api/v1/resources/build-cache— inspect Docker build cache usagePOST /api/v1/resources/build-cache/prune— prune the build cacheGET /api/v1/resources/host/summary— per-category counts and sizes of what Docker keeps on disk, and what can be freed.disk.reclaimableis what the Free-up-space defaults remove (unused images, build cache, stopped containers outside any compose project);disk.reclaimableAlladds 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 bodyGET /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.sizeis omitted when Docker did not report it. Removes nothingPOST /api/v1/resources/host/free-space— remove the listed items, body{images?, containers?, volumes?, networks?: string[], buildCache?: bool}(IDs ascandidatesreturns them, at most 1000 per category). Waits for no stack: it answers 409OPERATION_IN_PROGRESSwhile 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 whosedetailshas{removed, failed: [{id, reason}], skipped: [{id, reason}]}per category,buildCache: {requested, removed, spaceReclaimed, failed?, skipped?}, andspaceReclaimed, Docker's disk use before minus after (omitted when it could not be measured). Outcomesuccess,partial(207),no_change, orfailed(500) when every removal failed. 400VALIDATION_ERRORfor 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.categoriesholds 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.alertThresholdBytesis the dashboard alert threshold (default 5 GiB, 0 = off).nextRunAt(RFC3339) is the next scheduled run, present only while cleanup is enabled and scheduledPUT /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;categoriesmay 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.alertThresholdBytesmust 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 togetherPOST /api/v1/resources/cleanup/preview— what a cleanup would remove. Removes nothingPOST /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 onGET /api/v1/resources/cleanup/history— recent cleanup runs.limitdefaults to 50 and is capped at 100. Each run records thecategoriesit acted on (comma-separated), per-category counts (containersDeleted,volumesDeleted,networksDeleted) andotherBytesReclaimed.statusissuccessorfailed;skippedis reserved for a scheduled run that finds another operation holding its turn, which no run writes yet
GET /api/v1/ws/terminal/:id/:container— WebSocket PTY sessiondocker 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.
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: 404STACK_NOT_FOUNDfor an unknown stack, 409OPERATION_IN_PROGRESSwhile another operation holds the stack, 400VALIDATION_ERRORfor an unknown action, 503DOCKER_UNAVAILABLEwhen the daemon was unreachable at startup
GET /api/v1/ws/updates/jobs/:jobId— WebSocket stream of a single update job's progress, companion to the pollingGET /api/v1/resources/updates/jobs/:jobIdabove
GET /api/v1/backups/policies— list backup policiesPUT /api/v1/backups/policies/stack/:stackId— create/update a stack's backup policyDELETE /api/v1/backups/policies/stack/:stackId— remove a stack's backup policyGET /api/v1/backups/status— current backup engine availability and stateGET /api/v1/backups/history— run historyGET /api/v1/backups/runs/:runId— a single run's detailGET /api/v1/backups/snapshots— list restic snapshotsGET /api/v1/backups/snapshots/:snapshotId/preview— preview a snapshot's contents before restoringPOST /api/v1/backups/run— start a backup runGET /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 capPOST /api/v1/backups/restore— restore a stack from a snapshotPOST /api/v1/backups/dr-restore— disaster-recovery restore (whole instance, onto a fresh host)POST /api/v1/backups/prune— apply retention and prune old snapshotsPOST /api/v1/backups/verify— verify repository integrity by reading pack data (readDataSubsetdefaults to 5%;100%reads every pack). Answers 409BACKUP_BUSYwhile a backup, sync, restore, prune or another check runs:restic checklocks the repository exclusively, so the two cannot overlap. A check that loses that race after the 202 is recorded asskipped, neverfailed. WithverifyWeeklyon, the scheduler also runs one check (triggerscheduled, default subset) at the end of a scheduled backup cycle when no check ended insuccessorfailedin the last 7 days; a scheduled backup that falls due while it runs is recorded asskipped. A failed check is reported onlastVerifyand never stops later backupsPOST /api/v1/backups/repo/init— initialize the restic repositoryPOST /api/v1/backups/cloud/test— test the configured cloud remote's connectivity/credentialsGET /api/v1/ws/backups/run/:runId— WebSocket stream of a backup run's progressGET /api/v1/ws/backups/sync/:runId— WebSocket stream of a sync run's progressGET /api/v1/ws/backups/restore/:runId— WebSocket stream of a restore run's progressGET /api/v1/ws/backups/dr-restore/:runId— WebSocket stream of a DR-restore run's progressGET /api/v1/ws/backups/prune/:runId— WebSocket stream of a prune run's progressGET /api/v1/ws/backups/verify/:runId— WebSocket stream of a repository verification run's progress
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".
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.
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.
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.
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.
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.