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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
family | query | string | |
state | query | string | |
objectKind | query | string | min length 1, max length 64 |
objectId | query | string | min length 1, max length 200 |
cursor | query | string | min length 1, max length 200 |
limit | query | integer | default 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
approvalRequestId?: string
} | nullResponse 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
actionrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
day | query | string |
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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
idrequired | path | string | min 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"