Skip to content
bucker

API reference

operations

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

GET/orgs/{orgSlug}/operations

Requires bearerAuth

The organization’s governed operations, newest first. Filter by family, state or object; page with the opaque cursor. An operation in a project the caller cannot read is not listed.

Parameters

Parameters for GET /orgs/{orgSlug}/operations
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
familyquerystring
statequerystring
objectKindquerystringmin length 1, max length 64
objectIdquerystringmin length 1, max length 200
cursorquerystringmin length 1, max length 200
limitqueryintegerdefault 25, min 1, max 100

Response 200

{
  data: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    projectId: string | null
    state: string
    riskClass: string
    verdict: string | null
    requesterKind: string
    appliedAt: string | null
    expiresAt: string | null
    verifyAt: string | null
    revertedAt: string | null
    autoReverted: boolean
    createdAt: string
  }[]
  nextCursor: string | null
}

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}/operations \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/operations/{id}

Requires bearerAuth

One governed operation: the plan the approver saw, its state, verification verdict, TTL, the revert hint and the signed receipt.

Parameters

Parameters for GET /orgs/{orgSlug}/operations/{id}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Response 200

{
  id: string
  family: string
  action: string
  objectKind: string
  objectId: string
  projectId: string | null
  state: string
  riskClass: string
  verdict: string | null
  requesterKind: string
  appliedAt: string | null
  expiresAt: string | null
  verifyAt: string | null
  revertedAt: string | null
  autoReverted: boolean
  createdAt: string
  reason: string
  planDigest: string
  targetVersionBefore: string
  targetVersionAfter: string | null
  approvalRequestId: string | null
  reversibility: string
  ttlMinutes: integer | null
  onTtlEnd: string | null
  … 5 more
}

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}/operations/{id} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/operations/{id}/confirm

Requires bearerAuth

The requester confirms, with a FRESH step-up, once the hold has ended. Confirming records that the person who asked still wants it; the next sweep applies it. Refused before the hold ends, without the quorum, after expiry and to anyone but the requester.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/{id}/confirm
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  stepUp: {
    kind: "webauthn"
    nonce: string
    assertion: {
      credentialId: string
      clientDataJSON: string
      authenticatorData: string
      signature: string
    }
  } | {
    kind: "totp"
    code: string
  }
}

Response 200

{
  confirmed: true
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  }
  appliesOnNextSweep: true
}

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 POST https://api.bucker.io/orgs/{orgSlug}/operations/{id}/confirm \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/operations/{id}/confirm/challenge

Requires bearerAuth

Mints the step-up challenge the requester answers to confirm a held dual-control act. The decision-page challenge route refuses an APPROVED request ("nothing to confirm"), which is exactly the state a request is in once its quorum voted; this one serves the requester, for their own held act, in that state.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/{id}/confirm/challenge
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Response 200

Record<string, unknown>

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 POST https://api.bucker.io/orgs/{orgSlug}/operations/{id}/confirm/challenge \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/operations/{id}/reject

Requires bearerAuth

Any eligible person may reject a held dual-control act until it applies, including after the quorum voted yes: the hold is exactly the time for that.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/{id}/reject
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  reasonCode: "wrong_target" | "too_wide" | "not_needed" | "unsafe" | "evidence_insufficient" | "duplicate" | "stale" | "other"
  reasonText: string
  channel?: "dashboard" | "api" | "mcp" | "slack" | "push" | "chat" | "email"
}

Response 200

{
  rejected: true
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  }
}

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 POST https://api.bucker.io/orgs/{orgSlug}/operations/{id}/reject \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/operations/{id}/revert

Requires bearerAuth

Reverts an applied operation by submitting its stored inverse through the governed engine. The revert is classed from the inverse (a loosening revert asks): 200 when it applied, 202 with an approval request when it needs a person, and the same call with approvalRequestId applies the approved plan once.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/{id}/revert
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  approvalRequestId?: string
} | null

Response 200

{
  status: "reverted" | "approval_required" | "inert_draft"
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  }
  revertOperation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  } | null
  receiptSigned: boolean | null
  stoppedWindow: boolean | null
  approvalRequestId: string | null
  decisionUrl: string | null
}

Response 202

{
  status: "reverted" | "approval_required" | "inert_draft"
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  }
  revertOperation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  } | null
  receiptSigned: boolean | null
  stoppedWindow: boolean | null
  approvalRequestId: string | null
  decisionUrl: string | null
}

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 POST https://api.bucker.io/orgs/{orgSlug}/operations/{id}/revert \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/operations/{id}/vote

Requires bearerAuth

A step-up vote on a held dual-control act: the requester’s own vote at filing (below the line this applies the act), or an independent approver’s. The requester cannot vote twice and nobody in the delegation chain counts as independent.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/{id}/vote
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  stepUp: {
    kind: "webauthn"
    nonce: string
    assertion: {
      credentialId: string
      clientDataJSON: string
      authenticatorData: string
      signature: string
    }
  } | {
    kind: "totp"
    code: string
  }
  channel?: "dashboard" | "api" | "mcp" | "slack" | "push" | "chat" | "email"
  reason?: string
}

Response 200

{
  status: "voted" | "held" | "applied"
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  } | null
  approvals: integer | null
  independentApprovals: integer | null
}

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 POST https://api.bucker.io/orgs/{orgSlug}/operations/{id}/vote \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/operations/human-requester/{action}

Requires bearerAuth

A person files a dual-control act (an approval-policy loosening, a retention erase, an org export, ...). Needs a person on their own session: an OAuth-client token, an agent and a service principal are refused. Above the line the act holds (24 h by default) for an independent step-up vote and the requester’s fresh step-up confirmation; below it the requester’s step-up applies it at once. 202 while it waits, 200 when applied.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/human-requester/{action}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
actionrequiredpathstringmin length 3, max length 100

Request body (required) · application/json

{
  target?: {
    id: string
  }
  input: Record<string, unknown>
  stepUp?: {
    kind: "webauthn"
    nonce: string
    assertion: {
      credentialId: string
      clientDataJSON: string
      authenticatorData: string
      signature: string
    }
  } | {
    kind: "totp"
    code: string
  }
  channel?: "dashboard" | "api" | "mcp" | "slack" | "push" | "chat" | "email"
}

Response 200

{
  status: "step_up_required" | "held" | "applied"
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  }
  requestId: string
  line: "above" | "below" | null
  holdUntil: string | null
  independentVotesNeeded: integer | null
  decisionUrl: string
}

Response 202

{
  status: "step_up_required" | "held" | "applied"
  operation: {
    id: string
    family: string
    action: string
    objectKind: string
    objectId: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
    approvalRequestId: string | null
  }
  requestId: string
  line: "above" | "below" | null
  holdUntil: string | null
  independentVotesNeeded: integer | null
  decisionUrl: 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 -X POST https://api.bucker.io/orgs/{orgSlug}/operations/human-requester/{action} \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/operations/undo-digest

Requires bearerAuth

The acts agents applied without a human decision (policy ALLOW, review-mode automatic allow, or the AUTO_ATTEMPT rung) in a UTC day or the trailing 24 hours: each with its family, target, the signal before and after, the change verdict (or pending), whether anyone opened it, and the revert path. An act with a human vote never appears. Items in projects the caller cannot read are not listed.

Parameters

Parameters for GET /orgs/{orgSlug}/operations/undo-digest
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
dayquerystring

Response 200

{
  windowStart: string
  windowEnd: string
  counts: {
    total: integer
    open: integer
    reviewed: integer
    reverted: integer
    unreviewed: integer
    pendingVerdict: integer
  }
  families: {
    family: string
    total: integer
    unreviewed: integer
  }[]
  items: {
    operationId: string
    family: string
    action: string
    objectKind: string
    objectId: string
    projectId: string | null
    state: string
    requesterKind: string
    decidedBy: "allow" | "review_mode" | "auto_attempt"
    appliedAt: string
    signal: string | null
    before: number | null
    after: number | null
    verdict: "VALIDATED" | "INVALIDATED" | "HARMFUL" | "INCONCLUSIVE" | "NOT_MEASURED" | "pending"
    review: "open" | "reviewed" | "reverted" | "unreviewed"
    windowClosesAt: string
    listed: boolean
    revertable: boolean
    appPath: string
    revertPath: string
  }[]
  truncated: 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}/operations/undo-digest \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/operations/undo-digest/{id}/open

Requires bearerAuth

Records that a person who could have approved an undo-digest item opened it. Only an owner or admin acting for themselves counts; an agent, a service and an OAuth-client token are refused. Idempotent. An item nobody opens by the time its window closes is UNREVIEWED and counts for nothing in autonomy evidence.

Parameters

Parameters for POST /orgs/{orgSlug}/operations/undo-digest/{id}/open
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 64

Response 200

{
  operationId: string
  review: "open" | "reviewed" | "reverted" | "unreviewed"
  openedAt: 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 -X POST https://api.bucker.io/orgs/{orgSlug}/operations/undo-digest/{id}/open \
  -H "authorization: Bearer $BUCKER_TOKEN"