Long-poll: claim a Ready job whose runs_on matches the runner's labels
POST/api/runners/{runner_id}/claim
claimJob
Requires authentication using a bearer token — see tokens and scopes.
curl
curl -X POST 'https://neosource.dev/api/runners/RUNNER_ID/claim' \
-H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"labels":[]}'fetch
fetch("https://neosource.dev/api/runners/RUNNER_ID/claim", {
method: "POST",
headers: {
Authorization: "Bearer $NEOSOURCE_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({"labels":[]}),
});Path parameters
runner_idrequired
Request bodyrequired
application/json
Responses
200Claim or timeout sentinel
application/json
Standard errors
Bodies documented once for the whole API — see standard errors.
- 400Bad Request — one of: invalid_input
- 401Authentication required
- 403Forbidden — one of: forbidden
- 404Not Found — one of: not_found
- 409Conflict — one of: conflict
- 429Rate limited — retry after the `Retry-After` header
- 500Internal server error
- 503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
- 504Gateway timeout — the request exceeded the server's handling budget
Schemas
Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.
JobCacheTransferResponse
A job's cache transfer, measured by the server as it served the job's cache requests (`workflow_run_job_cache_transfer`). Every byte figure is COMPRESSED object bytes as the server sent or stored them (the actions/cache tarball, the build-cache pool object), never the unpacked size. A download counts when the server builds a hit response, at the entry's full size, even if the client aborts mid-body; a `lookup` or HEAD never counts. An upload counts only once durably stored. Every request that reaches the server counts once (a repeated pool PUT counts each time). Telemetry, not accounting: a crashed API node loses up to 30 s of counts, and nothing is ever counted twice.
native_restored_bytesBytes those restores sent. `null` exactly when `native_restores` is.
native_restoresactions/cache restore hits served to this job. `null` = not measured: the job's row predates restore tracking, so it may have restored. A job that ran during the deploy introducing this count may under-count (a restore served by a not-yet-updated node is missed).
native_save_skippedrequiredactions/cache saves refused because the key already existed (keys are immutable); they stored nothing.
native_saved_bytesrequirednative_savesrequiredactions/cache saves that stored a new entry.
pool_bytes_downrequiredBytes the pool's hits sent.
pool_bytes_uprequiredpool_getsrequiredBuild-cache pool GETs (a miss counts with 0 bytes).
pool_hitsrequiredpool_putsrequiredBuild-cache pool PUTs that stored, and their bytes.
CarriedFromResponse
Where a carried job ([`WorkflowRunJobResponse::carried_from`]) executed.
attemptrequiredThat run's `attempt`.
job_idrequiredThe job that executed (UUID hex).
run_idrequiredIts run — an earlier attempt of this run (UUID hex).
CompileCacheResponse
A job's compile-cache result, as SERVED to a reader: the raw counters plus the two figures derived from them. The derived fields are computed at read time rather than stored, so improving the model never means a migration and the inputs stay visible beside the output. Both are `null` where they have no meaning — notably `estimated_saved_ms` on a job that hit on everything and therefore never measured a compile.
compilationsrequiredcompile_msrequiredestimated_saved_msModelled ms the cache saved: `hits × (mean compile − mean cache read)`. `null` when the terms do not exist — see `JobCompileCache`.
hit_rateHits ÷ (hits + misses), or `null` when there were no requests.
hitsrequiredmissesrequiredread_hit_msrequiredrequestsrequired
RunnerBindingKind
Which trust binding a job executed under (ADR 0056 §1/§7). Serialized on the wire and in `workflow_run_jobs.executed_on` as the `snake_case` strings `hosted` / `workspace` / `actor`.
"hosted""workspace""actor"
WorkflowRunJobStatus
Lifecycle of an individual job inside a run. Distinct from the run-level status because `needs:` ordering means some jobs are `Waiting` while others are `Running`. The serde `snake_case` strings are the wire vocabulary the API emits (pinned by the `enum_wire_consistency` tests).
"waiting""ready""running""cancelling""succeeded""failed""cancelled""skipped"
WorkflowRunStepResponse
One step of a job, reported by the executing runner. Offsets index into the job's log byte stream (`GET /api/jobs/{job_id}/logs`), so the UI can slice the job log per step. `log_end_offset` is `null` while the step is in flight.
cache- one of
finished_atlog_end_offsetlog_start_offsetrequirednamerequiredstarted_atstatusrequiredstep_indexrequired
WorkflowRunEvent
A [`WorkflowRunCause`] with its payload stripped — the closed event vocabulary run list rows surface (`WorkflowRunResponse.event`). The serde `snake_case` strings are the wire vocabulary (pinned by the `enum_wire_consistency` tests).
"push""change""manual""schedule""pull_request""merge_group"
WorkflowRunLandedPullRequest
The merged PR a run's trigger commit landed from (`WorkflowRunResponse.landed_pull_request`).
numberrequiredtitlerequired
WorkflowRunStatus
Lifecycle of a workflow run. Mirrors the GHA-shaped surface that the SPA renders. The serde `snake_case` strings are the wire vocabulary the API emits (pinned by the `enum_wire_consistency` tests).
"pending_approval""queued""quota_blocked""concurrency_blocked""running""cancelling""succeeded""failed""cancelled"
WorkflowRunTestSummary
Per-run test results parsed from a `JUnit` report artifact at run completion. Counts are individual testcases.
failedrequiredfailuresrequiredFirst N failing tests (server caps the stored list).
itemspassedrequiredskippedrequiredtotalrequired
ToolchainManifest
Everything one run resolved, keyed by [`ToolchainKey::storage_key`]. Written once per run and read by every later reader — the second matrix leg, a re-run, a replay. Authoritative over the constraint that produced it: a re-run re-materializes these artifact identities rather than asking the catalog again (ADR 0083 §2).
catalog_versionsha256 of the catalog file that produced these entries. **Provenance only, never a lookup key.** The catalog is compiled into the binary, so a server running catalog C′ cannot evaluate against pinned catalog C — the rows are not in the process. Pinning a hash you cannot look up is a promise the deployment model cannot keep, which is why authority sits on the OUTPUT (ADR 0083 §2).
entries`storage_key` → what it resolved to.
additional propertiesunreadable`storage_key` → why a tolerant reader could not interpret that entry. **Populated only by a reader, never by the server.** The server writes what it can serialize, by construction, so this is empty in every row of `workflow_runs.toolchain_manifest`. A reader fills it in when it meets a [`ToolArtifact`] kind it predates and sets that one entry aside rather than failing the whole payload. A missing key and an unreadable key are NOT the same state: missing takes the late-bound resolve route and, failing that, an approximating local table; unreadable must REFUSE at the point of use. A job that never asks for an unreadable key runs untouched — that is what makes setting one entry aside safe at all. Additive on the wire (`default`, and skipped when empty), so an older reader ignores it and the common empty case costs nothing.
additional properties
ResolvedToolchain
What the catalog answered, and what a re-run re-materializes.
artifactrequiredtoolrequiredCanonical tool name (aliases resolve to it), or the raw name for a passthrough installable.
variantDistribution/vendor where the tool has one (`temurin`, `zulu`, …).
versionrequiredThe concrete version. **Open vocabulary, deliberately `String`** — the set of version strings is unbounded by construction, so this is the documented exception to the closed-set-DTO-enum rule.
DistLayout
How a dist archive unpacks into the tool-cache root.
"strip_one""flat"
StorePathArtifact
The `store_path` artifact's payload, with its invariants enforced. Two of them, and neither was a type before: 1. **`store_path` is a well-formed store path UNDER THE REAL STORE.** It deserializes straight out of `workflow_runs.toolchain_manifest` jsonb and [`ToolchainManifest::has_store_path`] is the agent's whole authorization surface, so as a raw `String` this answered "recorded" for anything that byte-matched a recorded entry — and left the grammar as the daemon's job alone rather than a property of the value. It takes BOTH halves to be that claim, and only the first was a type before: [`NixStorePath`] carries the GRAMMAR and is root-agnostic on purpose (the daemon's root is env-configurable and its own tests point it at a directory of their own), so `/etc/<hash>-passwd` is a shaped path and that type accepts it by design. [`StorePathArtifact::new`] pins the ROOT to [`NixStoreRoot::default`], on construction and on deserialize alike, which is what makes a recorded artifact naming anything outside the real store unconstructable. 2. **`bin_output` is one of `outputs`.** The `deno` → `denort` lesson is that which output carries `bin/` is index-ANSWERED, never guessed, and an answer naming an output the derivation did not have is not an answer. That was prose in a doc comment; it is checked here. `revision` stays an unvalidated `String` on purpose, and the asymmetry is the point: it is provenance only. No decision is made on it — that is exactly why [`ToolArtifact::nixpkgs_ref`] does not return it — so a malformed revision misleads a reader without routing anything, while a malformed store path is an authorization answer.
bin_outputrequiredWhich output `store_path` is. Index-answered, never guessed — the `deno` → `denort` lesson says a name heuristic is not enough. A member of `outputs` by construction.
outputsrequiredEvery output the derivation had, for provenance only.
itemsrevisionrequiredThe revision the index chose (ADR 0101 §2a records it "beside the store path"). Deliberately NOT named `nixpkgs_ref` and deliberately NOT returned by [`ToolArtifact::nixpkgs_ref`]: that accessor drives `group_by_ref` and the daemon's attr path on 8080, and a revision leaking there routes a ref that is not in `ALLOWED_REFS` — the 2026-07-31 403 storm.
store_pathrequired
NixStorePath
An absolute, well-formed store path — `<root>/<hash>-<name>` for SOME valid [`NixStoreRoot`] — validated on construction AND on deserialize. **The grammar is a property of the VALUE, not a step some caller remembers.** `ToolArtifact::StorePath` is deserialized straight out of `workflow_runs.toolchain_manifest` jsonb and is the agent's whole authorization surface (`ToolchainManifest::has_store_path`), so a raw `String` there would let `/etc/passwd` answer "recorded" the moment it byte-matched a recorded entry. Validating in `Deserialize` too is the half that matters: an invariant that holds only for freshly-built values is not an invariant, and every value on this path arrives from a database. Deliberately ROOT-INDEPENDENT: whether a path is under the root *this* process serves is [`store_path_leaf`]'s question, and that root is env-configurable. This type answers the other one — is it shaped like a store path at all. Which means the grammar alone is NOT the authorization answer, and the doc must not be read as claiming it is: `/etc` is a root [`NixStoreRoot`] admits, so `/etc/<hash>-passwd` is a well-formed value of this type. Pinning a RECORDED artifact to the real store is [`crate::model::toolchain::StorePathArtifact::new`]'s clause, one layer up, where the recording happens.