HTTP API reference

HTTP API reference

Every route the controller and logs service register, with the scope each requires, generated from the routing code. All paths are under the /api/v1 base (webhook and /metrics excepted). Scope enforcement and the token model are in auth.md; admin is the superset that satisfies any scope check. public routes run with no bearer check (the GitHub webhook is HMAC-verified instead; POST /api/v1/users self-selects unauthenticated bootstrap vs admin-scoped create).

ControllerSection anchor link

MethodPathScope
GET/api/v1/agentsruns.read
GET/api/v1/approvals/pendingruns.read
GET/api/v1/artifacts/{key}runs.read
GET/api/v1/auth/bootstrap-neededpublic
POST/api/v1/auth/loginpublic
POST/api/v1/auth/logoutpublic
GET/api/v1/auth/sessionpublic
GET/api/v1/auth/whoamipublic
POST/api/v1/concurrency/{key}/acquireadmin
POST/api/v1/concurrency/{key}/cancel-waiteradmin
POST/api/v1/concurrency/{key}/force-releaseadmin
POST/api/v1/concurrency/{key}/heartbeatadmin
GET/api/v1/concurrency/{key}/notifyruns.read
POST/api/v1/concurrency/{key}/releaseadmin
GET/api/v1/concurrency/{key}/resolveadmin
GET/api/v1/concurrency/{key}/stateruns.read
GET/api/v1/healthpublic
POST/api/v1/nodes/claimnodes.claim
GET/api/v1/pipelines/{name}/latestruns.read
GET/api/v1/poolruns.read
POST/api/v1/pool/checkoutadmin
POST/api/v1/pool/heartbeatadmin
POST/api/v1/pool/returnadmin
GET/api/v1/runsruns.read
POST/api/v1/runsadmin
DELETE/api/v1/runs/{id}admin
GET/api/v1/runs/{id}runs.read
GET/api/v1/runs/{id}/approvalsruns.read
GET/api/v1/runs/{id}/approvals/{nodeID}runs.read
POST/api/v1/runs/{id}/approvals/{nodeID}approvals.write
POST/api/v1/runs/{id}/approvals/{nodeID}/requestadmin
GET/api/v1/runs/{id}/attemptsruns.read
POST/api/v1/runs/{id}/cancelruns.write
GET/api/v1/runs/{id}/debug-pausesruns.read
POST/api/v1/runs/{id}/debug-pausesadmin
GET/api/v1/runs/{id}/eventsruns.read
POST/api/v1/runs/{id}/eventsadmin
POST/api/v1/runs/{id}/finishadmin
POST/api/v1/runs/{id}/heartbeatnodes.claim
GET/api/v1/runs/{id}/nodesruns.read
POST/api/v1/runs/{id}/nodesadmin
GET/api/v1/runs/{id}/nodes/{nodeID}nodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/activitynodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/annotationsnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/artifact-manifestnodes.claim
GET/api/v1/runs/{id}/nodes/{nodeID}/debug-pauseruns.read
POST/api/v1/runs/{id}/nodes/{nodeID}/depsadmin
GET/api/v1/runs/{id}/nodes/{nodeID}/dispatchruns.read
POST/api/v1/runs/{id}/nodes/{nodeID}/dispatchnodes.claim
GET/api/v1/runs/{id}/nodes/{nodeID}/dispatchesruns.read
POST/api/v1/runs/{id}/nodes/{nodeID}/finishadmin
POST/api/v1/runs/{id}/nodes/{nodeID}/heartbeatnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/mark-readynodes.claim
GET/api/v1/runs/{id}/nodes/{nodeID}/metricsruns.read
POST/api/v1/runs/{id}/nodes/{nodeID}/metricsnodes.claim
GET/api/v1/runs/{id}/nodes/{nodeID}/outputnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/releaseruns.write
POST/api/v1/runs/{id}/nodes/{nodeID}/revoke-readynodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/startadmin
POST/api/v1/runs/{id}/nodes/{nodeID}/statusadmin
POST/api/v1/runs/{id}/nodes/{nodeID}/steps/annotationsnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/steps/finishnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/steps/skipnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/steps/startnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/steps/summarynodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/summarynodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/touchnodes.claim
GET/api/v1/runs/{id}/pausedruns.read
POST/api/v1/runs/{id}/planadmin
GET/api/v1/runs/{id}/receiptruns.read
POST/api/v1/runs/{id}/retryruns.write
GET/api/v1/runs/{id}/stepsruns.read
GET/api/v1/secretsadmin
POST/api/v1/secretsadmin
DELETE/api/v1/secrets/{name}admin
GET/api/v1/secrets/{name}admin
GET/api/v1/servicespublic
GET/api/v1/tokensadmin
POST/api/v1/tokensadmin
DELETE/api/v1/tokens/{prefix}admin
GET/api/v1/tokens/{prefix}admin
POST/api/v1/tokens/{prefix}/rotateadmin
GET/api/v1/trendsruns.read
GET/api/v1/triggerstriggers.read
POST/api/v1/triggersruns.write
POST/api/v1/triggers/claimadmin
GET/api/v1/triggers/spawned-childtriggers.read
GET/api/v1/triggers/{id}triggers.read
POST/api/v1/triggers/{id}/doneadmin
POST/api/v1/triggers/{id}/heartbeatadmin
GET/api/v1/usersadmin
POST/api/v1/userspublic
DELETE/api/v1/users/{name}admin
GET/metricspublic
POST/webhooks/github/{pipeline}public

Logs serviceSection anchor link

MethodPathScope
GET/api/v1/healthpublic
GET/api/v1/logs/searchlogs.read
DELETE/api/v1/logs/{runID}logs.write
GET/api/v1/logs/{runID}logs.read
GET/api/v1/logs/{runID}/{nodeID}logs.read
POST/api/v1/logs/{runID}/{nodeID}logs.write
GET/api/v1/logs/{runID}/{nodeID}/streamlogs.read
GET/metricspublic