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); authenticated routes take any valid bearer and check no further scope.

ControllerSection anchor link

MethodPathScope
GET/api/v1/agentsruns.read
PUT/api/v1/agents/{name}admin
POST/api/v1/agents/{name}/heartbeatnodes.claim
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/whoamiauthenticated
GET/api/v1/compute-limitsruns.read
PUT/api/v1/compute-limitsadmin
POST/api/v1/concurrency/{key}/acquireruns.state
POST/api/v1/concurrency/{key}/cancel-waiteradmin
POST/api/v1/concurrency/{key}/force-releaseadmin
POST/api/v1/concurrency/{key}/heartbeatruns.state
GET/api/v1/concurrency/{key}/holderruns.state
GET/api/v1/concurrency/{key}/notifyruns.read
POST/api/v1/concurrency/{key}/releaseruns.state
GET/api/v1/concurrency/{key}/resolveruns.state
GET/api/v1/concurrency/{key}/stateruns.read
GET/api/v1/creditsruns.read
POST/api/v1/credits/grantsadmin
GET/api/v1/credits/historyruns.read
GET/api/v1/credits/settingsruns.read
PUT/api/v1/credits/settingsadmin
GET/api/v1/cronsruns.read
DELETE/api/v1/crons/reposruns.write
PUT/api/v1/crons/reposruns.write
GET/api/v1/crons/{id}runs.read
POST/api/v1/crons/{id}/disarmruns.write
DELETE/api/v1/crons/{id}/overrideruns.write
PUT/api/v1/crons/{id}/overrideruns.write
POST/api/v1/crons/{id}/pauseruns.write
POST/api/v1/crons/{id}/resumeruns.write
POST/api/v1/crons/{id}/runruns.write
GET/api/v1/egressadmin
POST/api/v1/gitcache/git/registeradmin
GET/api/v1/gitcache/git/{path...}admin
POST/api/v1/gitcache/git/{path...}admin
POST/api/v1/gitcache/refreshruns.write
POST/api/v1/gitcache/seedadmin
GET/api/v1/healthpublic
POST/api/v1/maintenance/reconcile-orphansadmin
POST/api/v1/nodes/claimnodes.claim
POST/api/v1/nodes/claim/preparenodes.claim
GET/api/v1/object-store/breakeradmin
POST/api/v1/object-store/reset-breakeradmin
GET/api/v1/pipelines/{name}/latestruns.read
GET/api/v1/pipelines/{name}/profilenodes.claim
POST/api/v1/pipelines/{name}/profile/contentionruns.state
POST/api/v1/pipelines/{name}/profile/observationsruns.state
PUT/api/v1/pipelines/{name}/profile/pinruns.state
POST/api/v1/pipelines/{name}/profile/waitsruns.state
GET/api/v1/poolruns.read
POST/api/v1/pool/checkoutadmin
POST/api/v1/pool/heartbeatadmin
POST/api/v1/pool/returnadmin
GET/api/v1/queue/stateruns.read
GET/api/v1/runsruns.read
POST/api/v1/runsruns.state
DELETE/api/v1/runs/{id}admin
GET/api/v1/runs/{id}runs.read or nodes.claim or triggers.claim
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}/eventsruns.state
POST/api/v1/runs/{id}/finishruns.state
POST/api/v1/runs/{id}/gitcache/git/registernodes.claim
GET/api/v1/runs/{id}/gitcache/git/{path...}nodes.claim
POST/api/v1/runs/{id}/gitcache/git/{path...}nodes.claim
POST/api/v1/runs/{id}/heartbeatnodes.claim
GET/api/v1/runs/{id}/nodesruns.read or nodes.claim or triggers.claim
POST/api/v1/runs/{id}/nodesruns.state
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
POST/api/v1/runs/{id}/nodes/{nodeID}/auto-retry/resetruns.state
GET/api/v1/runs/{id}/nodes/{nodeID}/bouncenodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/bounceruns.write
POST/api/v1/runs/{id}/nodes/{nodeID}/bounce/consumenodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/claimnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/claim/validatelogs.write
GET/api/v1/runs/{id}/nodes/{nodeID}/debug-pauseruns.read
POST/api/v1/runs/{id}/nodes/{nodeID}/depsruns.state
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}/execution-finishnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/execution-startnodes.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/finalize-readyruns.state
POST/api/v1/runs/{id}/nodes/{nodeID}/finishruns.state
POST/api/v1/runs/{id}/nodes/{nodeID}/heartbeatnodes.claim
GET/api/v1/runs/{id}/nodes/{nodeID}/logsruns.read or logs.read or nodes.claim or triggers.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/logsruns.state
GET/api/v1/runs/{id}/nodes/{nodeID}/logs/streamruns.read or logs.read or nodes.claim or triggers.claim
POST/api/v1/runs/{id}/nodes/{nodeID}/mark-readyruns.state
GET/api/v1/runs/{id}/nodes/{nodeID}/metricsruns.read or nodes.claim or triggers.claim
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-readyruns.state
POST/api/v1/runs/{id}/nodes/{nodeID}/startruns.state
POST/api/v1/runs/{id}/nodes/{nodeID}/statusruns.state
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
POST/api/v1/runs/{id}/nodes/{nodeID}/usagenodes.claim
GET/api/v1/runs/{id}/pausedruns.read
GET/api/v1/runs/{id}/pending-triggerstriggers.read or nodes.claim or triggers.claim
POST/api/v1/runs/{id}/planruns.state
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
POST/api/v1/secrets/rotateadmin
DELETE/api/v1/secrets/{name}admin
GET/api/v1/secrets/{name}secrets.read
GET/api/v1/servicesauthenticated
GET/api/v1/storageruns.read
PUT/api/v1/storage/quotas/{principal}admin
PUT/api/v1/storage/quotas/{principal}/allowanceadmin
PUT/api/v1/storage/settingsadmin
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}/meteredadmin
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/claimtriggers.claim
GET/api/v1/triggers/spawned-childtriggers.read
GET/api/v1/triggers/{id}triggers.read or nodes.claim or triggers.claim
POST/api/v1/triggers/{id}/claimtriggers.claim
POST/api/v1/triggers/{id}/donetriggers.claim
POST/api/v1/triggers/{id}/heartbeattriggers.claim
GET/api/v1/usersadmin
POST/api/v1/usersadmin
DELETE/api/v1/users/{name}admin
DELETE/api/v1/webhooks/github/bindingsadmin
POST/api/v1/webhooks/github/bindingsadmin
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