Skip to content
bucker

API reference

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

Parameters for GET /orgs/{orgSlug}/databases
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugquerystringmin length 1, max length 64
platformquery"digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 moreone 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

Parameters for POST /orgs/{orgSlug}/databases
NameInTypeNotes
orgSlugrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/databases/{id}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
idrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/databases/{id}/coverage/history
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
idrequiredpathstringmin length 1, max length 64
signalquery"statements" | "activity" | "waits" | "blocking" | "generic_plans" | "column_statistics" | "schema" | "settings" | … 7 moreone 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

Parameters for POST /orgs/{orgSlug}/databases/{id}/verify
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
idrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/databases/connect/{token}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
tokenrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/databases/setup-script
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
platformquery"digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 moredefault "self_hosted", one of "digitalocean" | "neon" | "supabase" | "rds" | "aurora" | "cloudsql" | "azure" | "fly" | … 3 more
includeCancelquery"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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/{connectionId}/sessions/cancel
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
connectionIdrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/databases/{connectionId}/sessions/cancels
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
connectionIdrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/databases/advisors
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/advisors/rules
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
connectionIdquerystringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals/{changeId}/deliver
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
changeIdrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals/{changeId}/refresh
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
changeIdrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/index-proposals/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/databases/queries
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
fromqueryunknown
toqueryunknown
environmentquerystringmin length 1, max length 64
connectionIdquerystringmin length 1, max length 64
limitqueryintegerdefault 20, min 1, max 50
cursorquerystringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/databases/queries/{fingerprint}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
fingerprintrequiredpathstringmin length 1, max length 80
fromqueryunknown
toqueryunknown
environmentquerystringmin length 1, max length 64
connectionIdquerystringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
queueIdrequiredpathstringmin length 1, max length 64
errorClassquerystringmin length 1, max length 80
olderThanMinutesqueryintegermin 0, max 525600
newerThanMinutesqueryintegermin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/excerpts/disable
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
queueIdrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/excerpts/enable
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
queueIdrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/purge
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
queueIdrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/redrive
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
queueIdrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/databases/queues/{queueId}/dead-letters/redrive/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
queueIdrequiredpathstringmin 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 '{ … }'