Long-poll: block until the job is cancelled

GET/api/jobs/{job_id}/cancel-watch

cancelWatch

Runner-protocol route (same lease-bearer auth as the log chunk POST). The runner parks here alongside its heartbeat; the server blocks — woken by a `ci_job_cancel` NOTIFY (ADR 0064 §3) — until the job is observed `cancelling`/`cancelled` and returns `{"cancelled": true}`, or the server-set wait cap elapses and it returns `{"cancelled": false}` (re-open the watch). The authoritative job-status re-read is the source of truth; the NOTIFY only shortcuts the wait.

Requires authentication using a bearer token — see tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/jobs/JOB_ID/cancel-watch' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN'

fetch

fetch("https://neosource.dev/api/jobs/JOB_ID/cancel-watch", {
  method: "GET",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
  },
});

Path parameters

job_idrequired: string

Responses

200Cancel observed, or timeout sentinel

application/json

CancelWatchResponse

object

cancelled: boolean
`true` once the job was observed `cancelling`/`cancelled` (or gone) server-side — the runner tears the job down and reports it `cancelled`. `false` is the long-poll timeout sentinel (the server caps the wait at `CANCEL_WATCH_CAP`); the runner simply re-opens the watch. The endpoint is bodyless (GET) — the wait cap is server-set, like `claim`'s. Defaulted for wire-compat.

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