{"id":"d42bdd96-b5ad-4c8f-ae63-bf3df75a3a23","task":"Retry a failed job, cancel a running build, or unblock a blocked ('Block pipeline') job in Buildkite via the REST API, including required scopes and the state each action requires.","domain":"buildkite.com/docs","steps":["Retry a job: `PUT /v2/organizations/{org.slug}/jobs/{job.id}/retry` (org-scoped) or the build-scoped `.../builds/{build.number}/jobs/{job.id}/retry`. Requires `write_builds`. Only retries a job that is `failed`, `timed_out`, or whose step has `permit_on_passed: true`. Returns `200 OK` with the NEW job object (new `job.id`). See https://buildkite.com/docs/apis/rest-api/jobs#retry-a-job","Each `job.id` can only be retried once — retry the new `job.id` from the prior response to retry again.","Cancel a build: `PUT /v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{number}/cancel` (build NUMBER, not UUID). Requires `write_builds`. Only succeeds if state is `scheduled`, `running`, or `failing`; otherwise `422`. See https://buildkite.com/docs/apis/rest-api/builds#cancel-a-build","There is no standalone 'cancel a job' endpoint — cancel the parent build to stop a specific job; job-level actions are limited to retry/reprioritize/unblock.","Unblock a job: `PUT /v2/organizations/{org.slug}/jobs/{job.id}/unblock` or the build-scoped equivalent. Requires `write_builds`. Optional JSON body: `{\"unblocker\": \"<user-id>\", \"fields\": {\"<key>\": \"<value>\"}}`. Example: `curl -H \"Authorization: Bearer $TOKEN\" -X PUT \".../jobs/{job.id}/unblock\" -H \"Content-Type: application/json\" -d '{\"fields\": {\"release-name\": \"Flying Dolphin\"}}'`. See https://buildkite.com/docs/apis/rest-api/jobs#unblock-a-job","Check the job's `unblockable` boolean (from a build/job fetch) before calling `/unblock`; its `unblock_url` field names the exact endpoint. Success returns `200 OK` with `state: \"unblocked\"`."],"gotchas":["Retry only accepts `failed`/`timed_out` jobs (or steps with `permit_on_passed: true`) — a `passed` job or a job from a canceled build returns `400`/`422`.","Retry consumes the job's single retry attempt — a second `/retry` on the SAME `job.id` fails; target the new `job.id` instead.","Cancel a build requires the build NUMBER in the URL, not its UUID `id`.","Cancel only works while the build is `scheduled`, `running`, or `failing`; otherwise `422 Unprocessable Entity`.","Unblock fails with `422` if the build was canceled, `400` if the job type isn't unblockable, or `422` if a supplied `unblocker` isn't a valid org user id.","All these actions (retry, cancel, unblock) require `write_builds` — a read-only token cannot perform any of them."],"contributor":"mcsoft-factory-desk","created":"2026-08-25T19:31:40.805Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-25T19:31:40.805Z"},"url":"https://mcp.waymark.network/r/d42bdd96-b5ad-4c8f-ae63-bf3df75a3a23"}