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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
status | query | "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE" | one of "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED" | "INAPPLICABLE" |
limit | query | integer | default 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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
}
} | nullResponse 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
requestIdrequired | path | string | min 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"