databases
24 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.
GET/orgs/{orgSlug}/databases
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlug | query | string | min length 1, max length 64 |
platform | query | "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more | one of "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more |
Response 200
{
databases: {
id: string
connectionId: string
project: {
id: string
slug: string
}
environment: string
platform: string
mode: string
usage: string
serverVersion: string | null
privileges: {
pg_read_all_stats: boolean
pg_stat_statements_installed: boolean
pg_stat_statements_select: boolean
explain: boolean
cancel: boolean
}
setupScriptVersion: string | null
breaker: {
state: "closed" | "open" | "half_open"
openedAt: string | null
reason: string | null
}
status: string
lastSuccessAt: string | null
lastErrorAt: string | null
lastError: string | null
excerpts: boolean
createdAt: string
}[]
total: number
}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}/databases \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/databases
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
projectSlug: string
}Response 201
{
connectionId: string
link: {
token: string
expiresAt: string
purpose: "read" | "signal" | "apply"
path: 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}/databases \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/databases/{id}
Requires bearerAuth
One customer database with its coverage matrix: every signal, its state (live, partial, missing, not_applicable or unknown), the reason and what a person does about it. There is no overall verdict. `detail` and `lastError` are untrusted server text.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
idrequired | path | string | min length 1, max length 64 |
Response 200
{
database: {
id: string
connectionId: string
project: {
id: string
slug: string
}
environment: string
platform: string
mode: string
usage: string
serverVersion: string | null
privileges: {
pg_read_all_stats: boolean
pg_stat_statements_installed: boolean
pg_stat_statements_select: boolean
explain: boolean
cancel: boolean
}
setupScriptVersion: string | null
breaker: {
state: "closed" | "open" | "half_open"
openedAt: string | null
reason: string | null
}
status: string
lastSuccessAt: string | null
lastErrorAt: string | null
lastError: string | null
excerpts: boolean
createdAt: string
}
coverage: {
observedAt: string
signals: {
signal: "statements" | "activity" | "waits" | "blocking" | "generic_plans" | "column_statistics" | "schema" | "settings" | … 7 more
state: "live" | "partial" | "missing" | "not_applicable" | "unknown"
reason: string | null
explanation: string | null
remedy: string | null
detail: string | null
since: string | null
lastSampleAt: string | null
evidence: object
}[]
counts: {
live: number
partial: number
missing: number
not_applicable: number
unknown: number
}
}
}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}/databases/{id} \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/databases/{id}/coverage/history
Requires bearerAuth
Changes of state of a database’s signals over the last thirty days, newest first. Written by the worker pass, so it can be empty on a database that has not been recorded yet.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
idrequired | path | string | min length 1, max length 64 |
signal | query | "statements" | "activity" | "waits" | "blocking" | "generic_plans" | "column_statistics" | "schema" | "settings" | … 7 more | one of "statements" | "activity" | "waits" | "blocking" | "generic_plans" | "column_statistics" | "schema" | "settings" | … 7 more |
Response 200
{
history: {
signal: string
state: string
reason: string | null
since: string
until: string | null
current: 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}/databases/{id}/coverage/history \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/databases/{id}/verify
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
idrequired | path | string | min length 1, max length 64 |
Response 200
{
ok: boolean
database: {
id: string
connectionId: string
project: {
id: string
slug: string
}
environment: string
platform: string
mode: string
usage: string
serverVersion: string | null
privileges: {
pg_read_all_stats: boolean
pg_stat_statements_installed: boolean
pg_stat_statements_select: boolean
explain: boolean
cancel: boolean
}
setupScriptVersion: string | null
breaker: {
state: "closed" | "open" | "half_open"
openedAt: string | null
reason: string | null
}
status: string
lastSuccessAt: string | null
lastErrorAt: string | null
lastError: string | null
excerpts: boolean
createdAt: string
}
problems: {
code: string
message: string
}[]
error: {
code: string
message: 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}/databases/{id}/verify \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/databases/connect/{token}
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
tokenrequired | path | string | min length 1, max length 256 |
Request body (required) · application/json
{
connectionString: string
caCertPem?: string
platform: "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more
environment: string
}Response 200
{
database: {
id: string
connectionId: string
project: {
id: string
slug: string
}
environment: string
platform: string
mode: string
usage: string
serverVersion: string | null
privileges: {
pg_read_all_stats: boolean
pg_stat_statements_installed: boolean
pg_stat_statements_select: boolean
explain: boolean
cancel: boolean
}
setupScriptVersion: string | null
breaker: {
state: "closed" | "open" | "half_open"
openedAt: string | null
reason: string | null
}
status: string
lastSuccessAt: string | null
lastErrorAt: string | null
lastError: string | null
excerpts: boolean
createdAt: string
}
problems: {
code: string
message: 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}/databases/connect/{token} \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/databases/setup-script
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
platform | query | "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more | default "self_hosted", one of "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more |
includeCancel | query | "true" | "false" | default "false", one of "true" | "false" |
Response 200
{
version: number
digest: string
platform: "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more
includesCancel: boolean
script: string
steps: string[]
notes: 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 https://api.bucker.io/orgs/{orgSlug}/databases/setup-script \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/databases/{connectionId}/sessions/cancel
Requires bearerAuth
Cancel the CURRENT STATEMENT of one backend of a customer database through the governed operation engine (db_session.cancel). The backend is pinned by pid, backend start, query start and statement fingerprint, read live; the apply re-reads all four and refuses TARGET_CHANGED if any moved, then calls the customer-installed bucker.cancel_backend (pg_cancel_backend only: sessions are never terminated). SENSITIVE with an ask floor: the first answer is always 202 with the decision link; after a person decides, the same body with approvalRequestId applies once (200). A database whose customer did not install the function answers unavailable.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
connectionIdrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
pid: integer
backendStart: string (date-time)
fingerprint?: string
reason: string
approvalRequestId?: string
}Response 200
{
status: "applied" | "approval_required" | "inert_draft"
operation: {
id: string
action: string
state: string
planDigest: string
targetVersionBefore: string
targetVersionAfter: string | null
riskClass: string
}
riskClass: string
plan: Record<string, unknown>
target?: {
found: boolean
state: string | null
role: string | null
applicationName: string | null
fingerprint: string | null
runtimeMs: integer | null
blockedCount: integer
longestWaitMs: integer
unreadable: string | null
cancelInstalled: boolean
refusal: {
code: string
reason: string
} | null
} | null
untrusted: string[]
decision?: "ALLOW" | "APPROVED"
versionAfter?: string
receiptSigned?: boolean
action?: {
id: string
connectionId: string
pid: integer
backendStart: string
fingerprint: string | null
approvalId: string | null
outcome: string
blockedBefore: integer
blockedAfter: integer | null
verifiedAt: string | null
createdAt: string
} | null
approvalRequestId?: string | null
decisionUrl?: string
refusal?: {
code: string
message: string
} | null
eligibleApprovers?: integer
minApprovers?: integer
}Response 202
{
status: "applied" | "approval_required" | "inert_draft"
operation: {
id: string
action: string
state: string
planDigest: string
targetVersionBefore: string
targetVersionAfter: string | null
riskClass: string
}
riskClass: string
plan: Record<string, unknown>
target?: {
found: boolean
state: string | null
role: string | null
applicationName: string | null
fingerprint: string | null
runtimeMs: integer | null
blockedCount: integer
longestWaitMs: integer
unreadable: string | null
cancelInstalled: boolean
refusal: {
code: string
reason: string
} | null
} | null
untrusted: string[]
decision?: "ALLOW" | "APPROVED"
versionAfter?: string
receiptSigned?: boolean
action?: {
id: string
connectionId: string
pid: integer
backendStart: string
fingerprint: string | null
approvalId: string | null
outcome: string
blockedBefore: integer
blockedAfter: integer | null
verifiedAt: string | null
createdAt: string
} | null
approvalRequestId?: string | null
decisionUrl?: string
refusal?: {
code: string
message: string
} | null
eligibleApprovers?: integer
minApprovers?: 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}/projects/{projectSlug}/databases/{connectionId}/sessions/cancel \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/databases/{connectionId}/sessions/cancels
Requires bearerAuth
The recent statement cancels of one database, newest first: the backend (pid, start, statement fingerprint), the approval that allowed it, the outcome (done, partial, identity_changed, refused, refused_by_cap or unavailable) and the blocked-session counts before and after. No statement text and no role or application name is returned.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
connectionIdrequired | path | string | min length 1, max length 64 |
Response 200
{
cancels: {
id: string
connectionId: string
pid: integer
backendStart: string
fingerprint: string | null
approvalId: string | null
outcome: string
blockedBefore: integer
blockedAfter: integer | null
verifiedAt: string | null
createdAt: 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 https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/databases/{connectionId}/sessions/cancels \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/projects/{projectSlug}/databases/advisors
Requires bearerAuth
The database advisor rules of one project: each rule with the thresholds in force and their published bounds, its version, state (shadow, live or retired) and published precision, and how many conditions are raised or being counted right now. The findings are ordinary issues.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Response 200
{
revision: integer
rules: {
kind: "seq_scan_selective" | "function_in_filter" | "index_unused" | "index_invalid" | "index_redundant" | "bloat_suspected" | "long_running" | "idle_in_transaction" | … 3 more
detectorId: string
title: string
enabled: boolean
version: integer
state: string
precision: {
value: number | null
labelledN: integer
}
thresholds: Record<string, number>
overridden: string[]
tunable: {
key: string
min: number
max: number
unit: string
default: number
firesMore: "up" | "down"
}[]
currentlyRaised: integer
held: integer
remedyLane: 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 https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/databases/advisors \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/databases/advisors/rules
Requires bearerAuth
Change one database advisor rule on this project through the governed operation engine: its thresholds (inside the published bounds) or its on/off switch. The act (db_advisor_rule.update) is derived from what would change, never from the body; a change that makes the rule fire less is a silence of at most 30 days that returns to the previous settings. The plan carries a replay over the rule's last 200 findings. 200 when applied; 202 with an approval request when a person must decide, after which the same body with approvalRequestId applies the approved plan once.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
rule: "seq_scan_selective" | "function_in_filter" | "index_unused" | "index_invalid" | "index_redundant" | "bloat_suspected" | "long_running" | "idle_in_transaction" | … 3 more
thresholds?: Record<string, integer>
enabled?: boolean
reason: string
approvalRequestId?: string
}Response 200
{
status: "applied" | "approval_required" | "inert_draft"
operation: {
id: string
action: string
state: string
planDigest: string
targetVersionBefore: string
targetVersionAfter: string | null
riskClass: string
}
riskClass: string
plan: Record<string, unknown>
decision?: "ALLOW" | "APPROVED"
versionAfter?: string
receiptSigned?: boolean
approvalRequestId?: string | null
decisionUrl?: string
refusal?: {
code: string
message: string
} | null
eligibleApprovers?: integer
minApprovers?: integer
}Response 202
{
status: "applied" | "approval_required" | "inert_draft"
operation: {
id: string
action: string
state: string
planDigest: string
targetVersionBefore: string
targetVersionAfter: string | null
riskClass: string
}
riskClass: string
plan: Record<string, unknown>
decision?: "ALLOW" | "APPROVED"
versionAfter?: string
receiptSigned?: boolean
approvalRequestId?: string | null
decisionUrl?: string
refusal?: {
code: string
message: string
} | null
eligibleApprovers?: integer
minApprovers?: 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}/projects/{projectSlug}/databases/advisors/rules \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals
Requires bearerAuth
The project's index proposals, newest first, with the state each has reached (proposed, pr_open, merged, deployed, validated, invalidated, inconclusive, rolled_back). Identifiers are the customer's own and untrusted.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
connectionId | query | string | min length 1, max length 64 |
Response 200
{
changes: {
id: string
connectionId: string
projectId: string
indexName: string
method: string
ddl: string
inverseDdl: string
state: string
delivery: string
prUrl: string | null
planDigest: string | null
createdAt: string
updatedAt: string
validation: 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}/projects/{projectSlug}/databases/index-proposals \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals
Requires bearerAuth
Propose an index through the governed operation engine. Bucker compiles CREATE INDEX CONCURRENTLY from the catalog identifiers (the body carries ids and names, never SQL), asks a person to approve the plan, and on approval opens ONE DRAFT pull request adding a migration in the project's mapped repository. Nothing is applied to the database and Bucker never merges. 200 when applied; 202 with an approval request when a person must decide, after which the same body with approvalRequestId applies the approved plan once.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
connectionId: string
fingerprints: string[]
schema?: string
table: string
columns: string[]
include?: string[]
method?: "btree" | "gin" | "brin"
reason: string
approvalRequestId?: string
}Response 200
{
status: "applied" | "approval_required" | "inert_draft"
operation: {
id: string
action: string
state: string
planDigest: string
targetVersionBefore: string
targetVersionAfter: string | null
riskClass: string
}
riskClass: string
plan: Record<string, unknown>
decision?: "ALLOW" | "APPROVED"
versionAfter?: string
receiptSigned?: boolean
approvalRequestId?: string | null
decisionUrl?: string
refusal?: {
code: string
message: string
} | null
eligibleApprovers?: integer
minApprovers?: integer
changeId?: string | null
delivery?: {
status: "opened" | "already_delivered" | "failed"
changeId: string | null
number: integer | null
url: string | null
branch: string | null
base: string | null
form: string | null
files: string[]
notes: string[]
reason: string | null
merged: false
draft: true
}
}Response 202
{
status: "applied" | "approval_required" | "inert_draft"
operation: {
id: string
action: string
state: string
planDigest: string
targetVersionBefore: string
targetVersionAfter: string | null
riskClass: string
}
riskClass: string
plan: Record<string, unknown>
decision?: "ALLOW" | "APPROVED"
versionAfter?: string
receiptSigned?: boolean
approvalRequestId?: string | null
decisionUrl?: string
refusal?: {
code: string
message: string
} | null
eligibleApprovers?: integer
minApprovers?: integer
changeId?: string | null
delivery?: {
status: "opened" | "already_delivered" | "failed"
changeId: string | null
number: integer | null
url: string | null
branch: string | null
base: string | null
form: string | null
files: string[]
notes: string[]
reason: string | null
merged: false
draft: 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}/projects/{projectSlug}/databases/index-proposals \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals/{changeId}/deliver
Requires bearerAuth
Open the draft pull request of an approved index proposal whose delivery failed (no repository mapped yet, a provider error). It needs no second approval, opens at most one pull request, and never merges.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
changeIdrequired | path | string | min length 1, max length 64 |
Response 200
{
status: "opened" | "already_delivered" | "failed"
changeId: string | null
number: integer | null
url: string | null
branch: string | null
base: string | null
form: string | null
files: string[]
notes: string[]
reason: string | null
merged: false
draft: 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}/projects/{projectSlug}/databases/index-proposals/{changeId}/deliver \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals/{changeId}/refresh
Requires bearerAuth
Read the table's next schema and move the proposal along: the index in the catalog is `deployed` (or `invalidated` when its build left it invalid), and after a day of traffic a verdict from the target statements' mean execution time before and after is recorded. Writes only Bucker's own bookkeeping row.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
changeIdrequired | path | string | min length 1, max length 64 |
Response 200
{
changeId: string
state: string
moved: boolean
detail: 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}/projects/{projectSlug}/databases/index-proposals/{changeId}/refresh \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals/preview
Requires bearerAuth
The statement Bucker would compile for an index and the evidence for it: CREATE INDEX CONCURRENTLY and its inverse, compiled from the catalog (never from caller text), the target statements and their share of database time, the table's counters, an estimated size, how many indexes a write maintains and the current generic plan. Writes nothing; refuses a partitioned table, an unknown column, a duplicate or redundant index.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
connectionId: string
fingerprints: string[]
schema?: string
table: string
columns: string[]
include?: string[]
method?: "btree" | "gin" | "brin"
}Response 200
{
status: "ok" | "refused"
connectionId: string
environment?: string
indexName?: string
qualifiedTable?: string
method?: string
columns?: string[]
include?: string[]
ddl?: string
inverseDdl?: string
existing?: {
id: string
indexName: string
state: string
}[]
evidence?: Record<string, unknown>
code?: string
reason?: 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}/projects/{projectSlug}/databases/index-proposals/preview \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/databases/queries
Requires bearerAuth
The top statements of a project by database time over a window (default 24 hours, at most 14 days): per fingerprint the database side from pg_stat_statements deltas and the application side from spans carrying the same fingerprint, with the endpoints that issue it. Statement text is untrusted customer text.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
from | query | unknown | |
to | query | unknown | |
environment | query | string | min length 1, max length 64 |
connectionId | query | string | min length 1, max length 64 |
limit | query | integer | default 20, min 1, max 50 |
cursor | query | string | min length 1, max length 64 |
Response 200
{
window: {
from: string
to: string
}
rows: {
fingerprint: string
text: string | null
command: string | null
tables: string[]
db: {
calls: number
totalExecMs: number
meanExecMs: number
maxExecMs: number
totalPlanMs: number
rows: number
rowsPerCall: number
sharedBlksHit: number
sharedBlksRead: number
tempBlksWritten: number
walBytes: number
dbTimeShare: number
hours: number
}
app: {
spans: number
p95Ms: number | null
sampledSpans: number
minSampleRate: number | null
endpoints: object[]
} | null
gaps: {
reset: boolean
evictedPartial: boolean
textsDiscarded: boolean
}
}[]
scanned: number
truncated: boolean
nextCursor: string | null
totalDbTimeMs: number
otherDbTimeMs: number
coverage: {
pillar: "on" | "off"
databases: number
collecting: number
dbSide: "live" | "stale" | "none"
appSide: "ok" | "timed_out"
matchedDbTimeShare: number | null
hoursWithGaps: {
reset: number
evictedPartial: number
textsDiscarded: number
}
collector: {
intervalMs: number
minGapMs: number
maxRowsPerPull: number
maxTextsPerPull: number
maxRowsPerHour: number
maxQueryIds: number
maxConcurrent: number
maxInFlightPerConnection: number
maxStatementsPerPull: number
pullDeadlineMs: number
statementTimeoutMs: number
}
}
}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}/projects/{projectSlug}/databases/queries \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/projects/{projectSlug}/databases/queries/{fingerprint}
Requires bearerAuth
One statement fingerprint: its database side (calls, time, rows, blocks, hourly, per role, the query ids that mapped to it) and its application side (spans, p95, endpoints, services, releases, sample traces). 404 when neither side knows it.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
fingerprintrequired | path | string | min length 1, max length 80 |
from | query | unknown | |
to | query | unknown | |
environment | query | string | min length 1, max length 64 |
connectionId | query | string | min length 1, max length 64 |
Response 200
{
fingerprint: string
text: string | null
textSource: "stored" | "span" | null
command: string | null
tables: string[]
queryIds: string[]
db: {
calls: number
totalExecMs: number
meanExecMs: number
maxExecMs: number
totalPlanMs: number
rows: number
rowsPerCall: number
sharedBlksHit: number
sharedBlksRead: number
tempBlksWritten: number
walBytes: number
dbTimeShare: number
hours: number
} | null
roles: {
role: string
calls: number
totalExecMs: number
}[]
hours: {
hour: string
calls: number
totalExecMs: number
basis: string
}[]
app: {
spans: number
p95Ms: number | null
sampledSpans: number
minSampleRate: number | null
endpoints: {
endpoint: string
spans: number
p95Ms: number | null
}[]
} | null
services: {
service: string
spans: number
}[]
releases: {
release: string
spans: number
p95Ms: number | null
}[]
sampleTraceIds: string[]
gaps: {
reset: boolean
evictedPartial: boolean
textsDiscarded: boolean
}
coverage: {
pillar: "on" | "off"
databases: number
collecting: number
dbSide: "live" | "stale" | "none"
appSide: "ok" | "timed_out"
matchedDbTimeShare: number | null
hoursWithGaps: {
reset: number
evictedPartial: number
textsDiscarded: number
}
collector: {
intervalMs: number
minGapMs: number
maxRowsPerPull: number
maxTextsPerPull: number
maxRowsPerHour: number
maxQueryIds: number
maxConcurrent: number
maxInFlightPerConnection: number
maxStatementsPerPull: number
pullDeadlineMs: number
statementTimeoutMs: number
}
}
}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}/projects/{projectSlug}/databases/queries/{fingerprint} \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters
Requires bearerAuth
A peek at a queue’s dead letters: at most five failed messages as metadata (id, time, attempts, error class, size, payload shape), the count the filter selects and whether it is exact. An excerpt of a body appears only where a person turned excerpts on for the queue, scrubbed and cut, and every excerpt read is written to the personal-data read ledger. Everything here is the customer’s text.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
queueIdrequired | path | string | min length 1, max length 64 |
errorClass | query | string | min length 1, max length 80 |
olderThanMinutes | query | integer | min 0, max 525600 |
newerThanMinutes | query | integer | min 1, max 525600 |
Response 200
{
queueId: string
provider: string | null
available: boolean
reason: string | null
peekEffect: "none" | "visibility_timeout" | null
excerptsEnabled: boolean
filterDigest: string
matching: {
count: number
exact: boolean
} | null
depth: number | null
messages: {
id: string
failedAt: string | null
attempts: number | null
errorClass: string | null
sizeBytes: number | null
shape: string[]
excerpt: 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}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/excerpts/disable
Requires bearerAuth
Turns excerpts of failed message bodies off for one queue, at once. A project admin narrows with no request; the audit row is the record.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
queueIdrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
reason: string
}Response 200
{
queueId: string
action: string
before: boolean
after: 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}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/excerpts/disable \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/excerpts/enable
Requires bearerAuth
Turns excerpts of failed message bodies on for one queue. Human-only (org:admin): it loosens which customer text agents read, and every excerpt read is written to the personal-data read ledger.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
queueIdrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
reason: string
}Response 200
{
queueId: string
action: string
before: boolean
after: 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}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/excerpts/enable \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/purge
Requires bearerAuth
A person’s purge of a queue’s dead letters. Human-only and dual control: it needs a person on their own session, an org policy row that allows it (the act is DENY until one exists), a second approver outside the requester’s chain, and an act credential that grants purge. No tool and no agent can request it.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
queueIdrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
reason: string
stepUp?: Record<string, unknown>
}Response 200
{
status: string
action: string
operationId: string
planDigest: string
riskClass: string
requestId: string | null
holdUntil: string | null
}Response 202
{
status: string
action: string
operationId: string
planDigest: string
riskClass: string
requestId: string | null
holdUntil: 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}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/purge \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/redrive
Requires bearerAuth
Moves failed messages back to their source queue, through the governed path: previewed first, asked, applied only with a yes bound to this plan, paced and capped, and stopped at the re-fail breach fixed at approval. 202 until the approval is given; retry with approvalRequestId.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
queueIdrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
filter?: {
errorClass?: string
olderThanMinutes?: integer
newerThanMinutes?: integer
}
cap?: integer
stopAfterRefailed?: integer
reason: string
approvalRequestId?: string
}Response 200
{
status: "applied" | "input_required" | "inert_draft"
action: string
operationId: string
planDigest: string
riskClass: string
approvalRequestId: string | null
outcome: string | null
moved: number | null
refailed: number | null
depthAfter: number | null
}Response 202
{
status: "applied" | "input_required" | "inert_draft"
action: string
operationId: string
planDigest: string
riskClass: string
approvalRequestId: string | null
outcome: string | null
moved: number | null
refailed: number | null
depthAfter: number | 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}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/redrive \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/redrive/preview
Requires bearerAuth
What a redrive would move, counted by the redrive’s own filter: the count, whether it is exact, the cap, the class it would be and why. Writes nothing. With a reason, and with queue:write, the preview is recorded as the evidence a run cites for 30 minutes.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
queueIdrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
filter?: {
errorClass?: string
olderThanMinutes?: integer
newerThanMinutes?: integer
}
cap?: integer
stopAfterRefailed?: integer
reason?: string
}Response 200
{
queueId: string
provider: string | null
filter: {
errorClass: string | null
olderThanMinutes: number | null
newerThanMinutes: number | null
}
filterDigest: string
count: number
exact: boolean
cap: number
willMove: number
stopAfterRefailed: number
depth: number | null
consumer: {
callsPayment: boolean | null
idempotent: boolean | null
}
redrivesLastHour: number
redrivesPerHour: number
indicativeClass: "SENSITIVE" | "CRITICAL"
reasons: string[]
refusal: {
code: string
reason: string
} | null
recorded: {
planDigest: string
validMinutes: number
derivedClass: 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}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/redrive/preview \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'