Skip to content
bucker

API reference

autonomy

3 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.

GET/orgs/{orgSlug}/autonomy/category-policies

Requires bearerAuth

Every operation category with Table F-14.1’s start and maximum rung and what this organization set. An organization can only lower a category below the table.

Parameters

Parameters for GET /orgs/{orgSlug}/autonomy/category-policies
NameInTypeNotes
orgSlugrequiredpathstringmin length 1

Response 200

{
  data: {
    category: string
    kind: string
    table: {
      startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
      maxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
      nonProductionOnly: boolean
    }
    org: {
      startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
      maxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
      enabled: boolean
    } | null
    effective: {
      startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
      maxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
      enabled: boolean
    }
  }[]
}

Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Request

curl https://api.bucker.io/orgs/{orgSlug}/autonomy/category-policies \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/autonomy/category-policies/{category}

Requires bearerAuth

ladder_category_policy.update: lowers a category’s maximum rung (or its start, or switches its earning off) for this organization. Human-only: refused to every agent, service and OAuth client. A value above Table F-14.1 is refused whoever asks. Audited with the previous value.

Parameters

Parameters for PUT /orgs/{orgSlug}/autonomy/category-policies/{category}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
categoryrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  maxRung?: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
  startRung?: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
  enabled?: boolean
}

Response 200

{
  category: string
  kind: string
  table: {
    startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    maxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    nonProductionOnly: boolean
  }
  org: {
    startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    maxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    enabled: boolean
  } | null
  effective: {
    startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    maxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    enabled: boolean
  }
}

Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Request

curl -X PUT https://api.bucker.io/orgs/{orgSlug}/autonomy/category-policies/{category} \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/autonomy/ladders

Requires bearerAuth

What an actor’s earned rung is in each operation category of Table F-14.1: the rung, the cap, the kind, every condition of the next rung that is not met with the ids it was read from, the shadow candidates counted, and what the actor may now do without asking. A category no registered family carries answers not_available.

Parameters

Parameters for GET /orgs/{orgSlug}/autonomy/ladders
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
actorrequiredquerystringmin length 1, max length 200
categoryquerystringmin length 1, max length 64
environmentClassquery"production" | "non_production"one of "production" | "non_production"

Response 200

{
  actor: {
    actorKey: string
    actorKind: "agent" | "oauth_client"
  }
  ladders: {
    category: string
    kind: string
    environmentClass: "production" | "non_production"
    availability: "available" | "not_available"
    unavailableReason: string | null
    rung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    cap: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    capReasons: string[]
    tableMaxRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    startRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT"
    minApprovers: {
      DRAFT_PR: number
      AUTO_ATTEMPT: number
      RCA_ONLY: number
    }
    nextRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT" | null
    offeredRung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT" | null
    eligible: boolean
    unmet: {
      id: "validated_streak" | "clean_recent" | "reversal_debt" | "no_incident" | "attention" | "shadow_trial"
      status: "met" | "unmet" | "unknown" | "not_available"
      detail: string
      evidenceIds: string[]
    }[]
    conditions: {
      id: "validated_streak" | "clean_recent" | "reversal_debt" | "no_incident" | "attention" | "shadow_trial"
      status: "met" | "unmet" | "unknown" | "not_available"
      detail: string
      evidenceIds: string[]
    }[]
    shadowCandidates: number
    mayDo: string
  }[]
}

Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Request

curl https://api.bucker.io/orgs/{orgSlug}/autonomy/ladders \
  -H "authorization: Bearer $BUCKER_TOKEN"