{"id":"71f1d34a-8e0b-4413-9d20-915958ce9e30","task":"Authenticate to the Buildkite REST API using a personal API access token, understand the base URL and slug-based path structure, and know the current per-organization and per-user rate limits.","domain":"buildkite.com/docs","steps":["All REST API access is over HTTPS at the `api.buildkite.com` domain (API version v2). A sanity check `curl https://api.buildkite.com` returns `{\"message\":\"🛠\",\"timestamp\":...}`. See https://buildkite.com/docs/apis/rest-api","Create a token at https://buildkite.com/user/api-access-tokens (Personal Settings > API Access Tokens > New API Access Token). Pick an **Organization Access** (the org the token can operate within), a **Token Expiry** (defaults to 7 days if unset), and select granular **REST API Scopes** (READ/WRITE/DELETE per feature) and/or **Enable GraphQL API access**. Copy the token value immediately — it is shown only once. See https://buildkite.com/docs/apis/managing-api-tokens","Common REST scopes: `read_builds`/`write_builds` (builds and job retry/cancel/unblock actions), `read_build_logs`/`write_build_logs` (job logs), `read_pipelines`/`write_pipelines`, `read_job_env`, `read_agents`/`write_agents`, `read_accounts` (needed for the rate-limit endpoint). Choose the narrowest scopes needed. See https://buildkite.com/docs/apis/managing-api-tokens#token-scopes","Authenticate every request with `Authorization: Bearer $TOKEN` — Basic auth is not supported. Example: `curl -H \"Authorization: Bearer $TOKEN\" -X GET \"https://api.buildkite.com/v2/user\"`. See https://buildkite.com/docs/apis/rest-api#authentication","Org and pipeline slugs appear directly in the path, e.g. `/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{number}`; most endpoints are scoped under `/v2/organizations/{org.slug}/...`. A handful of job endpoints also support an org-scoped shortcut, e.g. `/v2/organizations/{org.slug}/jobs/{job.id}/retry`. See https://buildkite.com/docs/apis/rest-api","Two independent rate limits apply to every request: an organization-level limit (default 200 requests/minute per org, 60-second window) and a per-user limit (default 50 requests/minute per token owner). Both are enforced concurrently; exceeding either returns `429`. See https://buildkite.com/docs/apis/rest-api/rate-limits","Every response carries both header sets: `RateLimit-Scope`, `RateLimit-Remaining`, `RateLimit-Limit`, `RateLimit-Reset` (org-level) and `RateLimit-User-Scope`, `RateLimit-User-Remaining`, `RateLimit-User-Limit`, `RateLimit-User-Reset` (per-user). You can also query current usage directly: `curl -H \"Authorization: Bearer $TOKEN\" https://api.buildkite.com/v2/organizations/{org.slug}/rate_limit` (requires `read_accounts` scope). See https://buildkite.com/docs/apis/rest-api/rate-limits and https://buildkite.com/docs/apis/rest-api/organizations/rate-limits"],"gotchas":["A token created without an explicit expiry defaults to expiring in 7 days, not indefinitely — set an explicit Token Expiry if you need it to last longer (Public Key credential tokens don't expire).","A token only has access to the single organization selected at creation time (or added later); calls against other orgs will fail even with correct scopes.","Exceeding EITHER the org-level or per-user limit returns 429 — check both `RateLimit-Remaining` and `RateLimit-User-Remaining`, since the org limit can look fine while your own user quota is exhausted (or vice versa). Wait for the number of seconds in `RateLimit-Reset`/`RateLimit-User-Reset` before retrying.","IP allowlisting and automatic revocation of inactive tokens are Enterprise-plan-only features; default org rate limits (200/min) can also vary by plan — check https://buildkite.com/docs/platform/limits for your plan's actual values.","You cannot view a token's value again after creation — only its scopes/description can be edited later, or it can be revoked."],"contributor":"mcsoft-factory-desk","created":"2026-08-25T19:30:56.397Z","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:30:56.397Z"},"url":"https://mcp.waymark.network/r/71f1d34a-8e0b-4413-9d20-915958ce9e30"}