Skip to content
bucker

API reference

subject-requests

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

GET/orgs/{orgSlug}/subject-requests

Requires bearerAuth

The organization’s subject requests, newest first: state, deadline (days left), window end, and the receipt summary. No identifier is ever returned. Cursor-paged.

Parameters

Parameters for GET /orgs/{orgSlug}/subject-requests
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
limitqueryintegermin 1, max 50
cursorquerystringmax length 200
statusquery"DRAFT" | "PENDING_WINDOW" | "EXECUTING" | "VERIFIED" | "CANCELLED" | "COMPLETED" | "FAILED" | "PENDING"one of "DRAFT" | "PENDING_WINDOW" | "EXECUTING" | "VERIFIED" | "CANCELLED" | "COMPLETED" | "FAILED" | "PENDING"

Response 200

{
  requests: {
    id: string
    kind: "ACCESS" | "ERASURE_END_USER"
    status: "DRAFT" | "PENDING_WINDOW" | "EXECUTING" | "VERIFIED" | "CANCELLED" | "COMPLETED" | "FAILED" | "PENDING"
    createdAt: string
    deadlineAt: string | null
    deadlineInDays: number | null
    windowEndsAt: string | null
    completedAt: string | null
    totalRows: number | null
    storesReached: number | null
    verifiedAll: boolean | null
    receiptSeq: number | null
    hasExport: boolean
  }[]
  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}/subject-requests \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/subject-requests

Requires bearerAuth

File a subject request as a DRAFT: the identifiers are resolved into every store’s references, the reach report (counts per store, never a value) is built, the identifiers are sealed in the draft and nowhere else, and the Art. 12(3) deadline (one month from receipt) is stamped. At most 20 unsubmitted drafts per organization. Changes no data. A person on their own session only: an agent, a service principal or an OAuth client files through the governed `subject_request_draft_create` tool (403 `SUBJECT_REQUEST_DRAFT_GOVERNED`).

Parameters

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

Request body (required) · application/json

{
  kind: "ACCESS" | "ERASURE_END_USER"
  identifiers: {
    email?: string (email)
    userId?: string
    username?: string
    ipAddress?: string (ipv4) | string (ipv6)
  }
  projectSlug?: string
  receivedAt?: string (date-time)
}

Response 201

{
  id: string
  kind: "ACCESS" | "ERASURE_END_USER"
  status: "DRAFT"
  deadlineAt: string
  report: {
    selectionFingerprint: string
    reachDigest: string
    projects: {
      projectId: string
      projectSlug: string
    }[]
    totalRows: integer
    stores: {
      storeId: string
      label: string
      reached: integer
      counts: object
      truncated: boolean
      unreachable: object | null
      removal: object
      hidesAtOnce: boolean
    }[]
    unresolvableGenerations: integer[]
    generatedAt: 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}/subject-requests \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/subject-requests/{id}

Requires bearerAuth

One subject request and its reach report. No identifier.

Parameters

Parameters for GET /orgs/{orgSlug}/subject-requests/{id}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 100

Response 200

{
  request: {
    id: string
    kind: "ACCESS" | "ERASURE_END_USER"
    status: "DRAFT" | "PENDING_WINDOW" | "EXECUTING" | "VERIFIED" | "CANCELLED" | "COMPLETED" | "FAILED" | "PENDING"
    createdAt: string
    deadlineAt: string | null
    deadlineInDays: number | null
    windowEndsAt: string | null
    completedAt: string | null
    totalRows: number | null
    storesReached: number | null
    verifiedAll: boolean | null
    receiptSeq: number | null
    hasExport: boolean
  }
  report: {
    selectionFingerprint: string
    reachDigest: string
    projects: {
      projectId: string
      projectSlug: string
    }[]
    totalRows: integer
    stores: {
      storeId: string
      label: string
      reached: integer
      counts: object
      truncated: boolean
      unreachable: object | null
      removal: object
      hidesAtOnce: boolean
    }[]
    unresolvableGenerations: integer[]
    generatedAt: 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}/subject-requests/{id} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/subject-requests/{id}/cancel

Requires bearerAuth

Cancel a draft, or an erasure inside its cancel window. Nothing is executed and the hold is released. A person on their own session only; an erasure past its window, or executing, is 409.

Parameters

Parameters for POST /orgs/{orgSlug}/subject-requests/{id}/cancel
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 100

Request body (required) · application/json

{
  reason: string
}

Response 200

{
  id: string
  kind: "ACCESS" | "ERASURE_END_USER"
  status: "DRAFT" | "PENDING_WINDOW" | "EXECUTING" | "VERIFIED" | "CANCELLED" | "COMPLETED" | "FAILED" | "PENDING"
  createdAt: string
  deadlineAt: string | null
  deadlineInDays: number | null
  windowEndsAt: string | null
  completedAt: string | null
  totalRows: number | null
  storesReached: number | null
  verifiedAll: boolean | null
  receiptSeq: number | null
  hasExport: 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}/subject-requests/{id}/cancel \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/subject-requests/{id}/execute

Requires bearerAuth

The human act. An ERASURE request is executed through the dual-control path: at or below 10,000 rows with a step-up (the cancel window is the second look), above it with two approvers outside your chain, a 24-hour hold and a confirmation. The body names the selection fingerprint and total the reach report showed: a changed selection (subject or projects) fails closed with 409 here and at the apply; a changed total is a 409 carrying `currentRows` to acknowledge. Execution HIDES the matched rows at once and PURGES them after the cancel window (72 hours unless 0 to 168 is given). An ACCESS request builds its export and returns a signed download link. A person on their own session only; 202 while an erasure waits.

Parameters

Parameters for POST /orgs/{orgSlug}/subject-requests/{id}/execute
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 100

Request body (required) · application/json

{
  reason?: string
  acknowledgeSelection?: string
  acknowledgeRows?: integer
  windowHours?: integer
  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

{
  kind: "erasure" | "access"
  status: string
  operationId: string | null
  requestId: string | null
  holdUntil: string | null
  independentVotesNeeded: integer | null
  decisionUrl: string | null
  export: {
    requestId: string
    rows: integer
    storesWithRows: integer
    bytes: integer
    sha256: string
    link: {
      token: string
      expiresAt: string
    }
  } | null
}

Response 202

{
  kind: "erasure" | "access"
  status: string
  operationId: string | null
  requestId: string | null
  holdUntil: string | null
  independentVotesNeeded: integer | null
  decisionUrl: string | null
  export: {
    requestId: string
    rows: integer
    storesWithRows: integer
    bytes: integer
    sha256: string
    link: {
      token: string
      expiresAt: 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}/subject-requests/{id}/execute \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/subject-requests/{id}/export

Requires bearerAuth

The end-user access export (GDPR Art. 15 and 20). Without `token`: a 15-minute signed link to the sealed bundle (the request must be executed first). With `token`: the bundle itself, every store’s rows for the subject plus who read person-level data in the covered projects. Bound to the organization, the request and the person the link was minted for.

Parameters

Parameters for GET /orgs/{orgSlug}/subject-requests/{id}/export
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 100
tokenquerystringmin length 20, max length 2000

Response 200

{
  requestId: string
  rows: integer
  storesWithRows: integer
  bytes: integer
  sha256: string
  link: {
    token: string
    expiresAt: string
  }
} | 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 https://api.bucker.io/orgs/{orgSlug}/subject-requests/{id}/export \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/subject-requests/{id}/receipt

Requires bearerAuth

The receipt of a verified erasure: per store, rows reached and removed, whether verification found nothing, when removal completed or is expected, and why a store was not reached. It contains no identifier. 404 until the request is verified.

Parameters

Parameters for GET /orgs/{orgSlug}/subject-requests/{id}/receipt
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 100

Response 200

{
  requestId: string
  selectionDigest: string
  stores: {
    storeId: string
    reached: integer
    removed: integer
    verified: boolean
    hiddenAt: string | null
    removedAt: string | null
    pendingUntil: string | null
    unreachableReason: string | null
    counts: Record<string, integer>
  }[]
  windowEndsAt: string | null
  deadlineAt: string
  executedAt: string
  completedAt: string | null
  receiptSeq: integer | null
  verifiedAll: 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}/subject-requests/{id}/receipt \
  -H "authorization: Bearer $BUCKER_TOKEN"