Skip to content
bucker

API reference

approval-requests

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

GET/orgs/{orgSlug}/approval-requests

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/approval-requests
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
statusquery"PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"one of "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
limitqueryintegerdefault 50, min 1, max 100

Response 200

{
  data: {
    id: string
    orgId: string
    requesterPrincipalId: string
    onBehalfOfPrincipalId: string | null
    action: string
    riskClass: string
    targetType: string
    targetId: string
    status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
    minApprovers: integer
    policyId: string | null
    deciderPrincipalId: string | null
    decidedAt: string | null
    reason: string | null
    expiresAt: string
    createdAt: string
    reasonCode?: string | null
    decisionChannel?: string | null
    batchId?: string | null
    queuePosition?: integer | null
    payload: unknown | null
    target?: {
      label: string
      title: string | null
      projectSlug: string | null
    } | 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}/approval-requests \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/approval-requests

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/approval-requests
NameInTypeNotes
orgSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  action: string
  targetType: string
  targetId: string
  projectTag?: string | null
  summary?: string | null
  ttlMinutes?: integer
  channelIds?: string[]
  notify?: boolean
}

Response 200

{
  decision: "ALLOW" | "ASK" | "DENY"
  riskClass: string
  reason: string
  minApprovers: integer
  policySource: string
  request: {
    id: string
    orgId: string
    requesterPrincipalId: string
    onBehalfOfPrincipalId: string | null
    action: string
    riskClass: string
    targetType: string
    targetId: string
    status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
    minApprovers: integer
    policyId: string | null
    deciderPrincipalId: string | null
    decidedAt: string | null
    reason: string | null
    expiresAt: string
    createdAt: string
    reasonCode?: string | null
    decisionChannel?: string | null
    batchId?: string | null
    queuePosition?: integer | null
    payload: unknown | null
    target?: {
      label: string
      title: string | null
      projectSlug: string | null
    } | null
  } | null
  deliveries: {
    channelId: string | null
    kind: string
    delivered: boolean
    error: string | null
  }[]
}

Response 201

{
  decision: "ALLOW" | "ASK" | "DENY"
  riskClass: string
  reason: string
  minApprovers: integer
  policySource: string
  request: {
    id: string
    orgId: string
    requesterPrincipalId: string
    onBehalfOfPrincipalId: string | null
    action: string
    riskClass: string
    targetType: string
    targetId: string
    status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
    minApprovers: integer
    policyId: string | null
    deciderPrincipalId: string | null
    decidedAt: string | null
    reason: string | null
    expiresAt: string
    createdAt: string
    reasonCode?: string | null
    decisionChannel?: string | null
    batchId?: string | null
    queuePosition?: integer | null
    payload: unknown | null
    target?: {
      label: string
      title: string | null
      projectSlug: string | null
    } | null
  } | null
  deliveries: {
    channelId: string | null
    kind: string
    delivered: boolean
    error: 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}/approval-requests \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/approval-requests/{requestId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/approval-requests/{requestId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Response 200

{
  id: string
  orgId: string
  requesterPrincipalId: string
  onBehalfOfPrincipalId: string | null
  action: string
  riskClass: string
  targetType: string
  targetId: string
  status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
  minApprovers: integer
  policyId: string | null
  deciderPrincipalId: string | null
  decidedAt: string | null
  reason: string | null
  expiresAt: string
  createdAt: string
  reasonCode?: string | null
  decisionChannel?: string | null
  batchId?: string | null
  queuePosition?: integer | null
  payload: unknown | null
  target?: {
    label: string
    title: string | null
    projectSlug: string | null
  } | 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}/approval-requests/{requestId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/approval-requests/{requestId}/approve

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/approval-requests/{requestId}/approve
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Request body (required) · application/json

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

Response 200

{
  request: {
    id: string
    orgId: string
    requesterPrincipalId: string
    onBehalfOfPrincipalId: string | null
    action: string
    riskClass: string
    targetType: string
    targetId: string
    status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
    minApprovers: integer
    policyId: string | null
    deciderPrincipalId: string | null
    decidedAt: string | null
    reason: string | null
    expiresAt: string
    createdAt: string
    reasonCode?: string | null
    decisionChannel?: string | null
    batchId?: string | null
    queuePosition?: integer | null
    payload: unknown | null
    target?: {
      label: string
      title: string | null
      projectSlug: string | null
    } | null
  }
  approvals: integer
  remaining: integer
  hasIndependentApprover: boolean
  idempotent: 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 POST https://api.bucker.io/orgs/{orgSlug}/approval-requests/{requestId}/approve \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/approval-requests/{requestId}/decision-page

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/approval-requests/{requestId}/decision-page
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Response 200

{
  request: {
    id: string
    orgId: string
    action: string
    riskClass: string
    status: string
    targetType: string
    targetId: string
    target: {
      label: string
      title: string | null
      projectSlug: string | null
    } | null
    minApprovers: integer
    requesterPrincipalId: string
    createdAt: string
    expiresAt: string
    decidedAt: string | null
    reason: string | null
    reasonCode: string | null
    decisionChannel: string | null
  }
  digest: string
  plan: unknown | null
  planText: string | null
  card: {
    version: 2
    builtAt: string
    plan: {
      before: string | null
      after: string | null
      text: string | null
      digest: string
    }
    target: {
      type: string
      id: string
      version: string | null
    }
    context: {
      readAt: string
      issueEssence: object | null
      alert: object | null
      traceSummary: object | null
      sessions: object | null
      flag: object | null
      release: object | null
      unavailable: string[]
    }
    effect: {
      action: string
      riskClass: string
      blastRadius: object | null
      inverse: string | null
      ttl: object | null
      verificationSignal: object | null
    }
    spend: {
      thisRequest: object
      incidentToDate: object[] | null
      pauses?: object[]
    }
    chain: {
      requesterPrincipalId: string
      requesterKind: string | null
      onBehalfOfPrincipalId: string | null
    }
    policy: {
      reason: string | null
      matched: object
    }
    claims?: {
      state: "checked" | "unchecked" | "contradicted"
      counts: object
      items: object[]
      omitted: integer
      computedAt: string
    }
    untrustedFields: string[]
    truncated: boolean
    estimatedTokens: integer
  } | null
  chain: {
    principalId: string
    kind: string
    displayName: string | null
    role: "requester" | "on_behalf_of" | "delegator"
  }[]
  policy: {
    policyId: string | null
    source: "policy" | "default"
    minApprovers: integer
    riskClass: string
  }
  votes: {
    approvals: integer
    remaining: integer
    yourVote: "APPROVE" | "REJECT" | null
  }
  stepUp: {
    required: boolean
    reason: "critical" | "dual_control" | null
    methods: "webauthn" | "totp"[]
    enrolUrl: string | null
  }
  canDecide: boolean
  cannotDecideReason: {
    code: "not_human" | "not_authorized" | "in_delegation_chain" | "not_pending" | "already_voted"
    message: string
  } | null
  batch: {
    id: string
    size: integer
    digest: string
    decidableCount: integer
  } | null
  queue: {
    position: integer
  } | null
  dualControl: {
    required: true
    needed: integer
    counted: integer
    independent: integer
    neededIndependent: integer
    securityKeyConfirmed: boolean
    shortfall: "needs_more_approvers" | "needs_independent_approver" | "needs_security_key" | null
    holdUntil: string | null
    holdHours: integer
    approverSet: {
      minApprovers: integer
      members: integer
    } | null
  } | null
  preAuthorization: {
    terms: {
      breach: object
      action: string
      expiresAt: string
    }
    defaultTicked: false
    mode: "shadow" | "applying"
    allows: string
    never: string
    canTick: boolean
  } | 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}/approval-requests/{requestId}/decision-page \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/approval-requests/{requestId}/narrow

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/approval-requests/{requestId}/narrow
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Request body (required) · application/json

{
  field: string
  direction: "down" | "subset" | "earlier"
  value: number | string | string | number[] | Record<string, number>
}

Response 200

{
  requestId: string
  status: string
  fromDigest: string
  digest: string
  diff: {
    field: string
    from: unknown
    to: unknown
  }[]
  derivedClass: string
  votesVoided: integer
}

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}/approval-requests/{requestId}/narrow \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/approval-requests/{requestId}/narrowing

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/approval-requests/{requestId}/narrowing
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Response 200

{
  requestId: string
  narrowable: boolean
  unavailableReason: string | null
  canNarrow: boolean
  cannotNarrowReason: string | null
  fields: {
    field: string
    direction: "down" | "subset" | "earlier"
    current: unknown
    original: unknown
  }[]
  original: {
    digest: string
    planText: string | null
    ttlMinutes: number | null
    blastRadius: unknown
    riskClass: string
  }
  current: {
    digest: string
    planText: string | null
    ttlMinutes: number | null
    blastRadius: unknown
    riskClass: string
  }
  narrowed: boolean
  narrowedAt: string | null
  diff: {
    field: string
    from: unknown
    to: 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 https://api.bucker.io/orgs/{orgSlug}/approval-requests/{requestId}/narrowing \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/approval-requests/{requestId}/reject

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/approval-requests/{requestId}/reject
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Request body (required) · application/json

{
  reasonCode: "wrong_target" | "too_wide" | "not_needed" | "unsafe" | "evidence_insufficient" | "duplicate" | "stale" | "other"
  reasonText?: string
  reason?: string
  channel?: "dashboard" | "api" | "mcp" | "slack" | "push" | "chat" | "email"
  stepUp?: {
    kind: "webauthn"
    nonce: string
    assertion: {
      credentialId: string
      clientDataJSON: string
      authenticatorData: string
      signature: string
    }
  } | {
    kind: "totp"
    code: string
  }
}

Response 200

{
  request: {
    id: string
    orgId: string
    requesterPrincipalId: string
    onBehalfOfPrincipalId: string | null
    action: string
    riskClass: string
    targetType: string
    targetId: string
    status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE"
    minApprovers: integer
    policyId: string | null
    deciderPrincipalId: string | null
    decidedAt: string | null
    reason: string | null
    expiresAt: string
    createdAt: string
    reasonCode?: string | null
    decisionChannel?: string | null
    batchId?: string | null
    queuePosition?: integer | null
    payload: unknown | null
    target?: {
      label: string
      title: string | null
      projectSlug: string | null
    } | null
  }
  approvals: integer
  remaining: integer
  hasIndependentApprover: boolean
  idempotent: 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 POST https://api.bucker.io/orgs/{orgSlug}/approval-requests/{requestId}/reject \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/approval-requests/{requestId}/step-up/challenge

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/approval-requests/{requestId}/step-up/challenge
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
requestIdrequiredpathstringmin length 1

Response 200

{
  requestId: string
  digest: string
  expiresAt: string
  methods: "webauthn" | "totp"[]
  webauthn: {
    challenge: string
    nonce: string
    rpId: string
    timeout: integer
    userVerification: "discouraged"
    allowCredentials: {
      type: "public-key"
      id: string
      transports: string[]
    }[]
  } | null
  enrolUrl: 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}/approval-requests/{requestId}/step-up/challenge \
  -H "authorization: Bearer $BUCKER_TOKEN"