Skip to content
bucker

API reference

infra

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

DELETE/orgs/{orgSlug}/infra/vercel/{teamId}

Requires bearerAuth

Uninstalls Bucker's record of a Vercel team: disables the integration and removes Bucker's drain rows. Bucker holds no token for the team, so the drains on Vercel's side stop when the integration is removed there; the answer says so.

Parameters

Parameters for DELETE /orgs/{orgSlug}/infra/vercel/{teamId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
teamIdrequiredpathstringmin length 1, max length 80

Response 200

{
  integrationId: string
  teamId: string
  drainRowsRemoved: integer
  vercelSideRemoved: false
  remedy: 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 DELETE https://api.bucker.io/orgs/{orgSlug}/infra/vercel/{teamId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/infra/vercel/install

Requires bearerAuth

Starts Bucker's Vercel marketplace install: a proposed connection, a single-use link used as the OAuth state, and the plan of what the install creates. A person's act.

Parameters

Parameters for POST /orgs/{orgSlug}/infra/vercel/install
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  projectSlug: string
}

Response 201

{
  authorizeUrl: string
  connectionId: string
  expiresAt: string
  plan: {
    creates: {
      resource: string
      detail: string
    }[]
    scope: string
    neverCreates: string[]
    requestedScopes: 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}/infra/vercel/install \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/infra/vercel/install/callback

Requires bearerAuth

The OAuth callback of the Vercel install, posted by the dashboard from the person's session with the state, code and installation. Consumes the state once, creates the log and trace drains and records the team.

Parameters

Parameters for POST /orgs/{orgSlug}/infra/vercel/install/callback
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  state: string
  code: string
  configurationId: string
  teamId?: string
}

Response 200

{
  integrationId: string
  teamId: string
  connectionId: string
  projectId: string
  grantedScopes: string[]
  logDrainId: string | null
  traceDrainId: string | null
  reinstall: boolean
  readLink: {
    token: string
    expiresAt: string
    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}/infra/vercel/install/callback \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
includequerystringmax length 200

Response 200

{
  profiles: {
    kind: "fly" | "serverless" | "render" | "vm" | "k8s_small"
    title: string
    unit: string
    enabled: boolean
    revision: integer
    tier: "minimal" | "standard"
    intervalSeconds: integer
    excludedMetrics: integer
    seriesPerEntity: integer
    unitsPerEntityMonth: {
      current: number
      proposed: number
    }
    components: string[]
    revisions: number | string[][]
  }[]
  available: {
    kind: "fly" | "serverless" | "render" | "vm" | "k8s_small"
    unit: string
    seriesPerEntity: integer
    unitsPerEntityMonth: {
      current: number
      proposed: number
    }
  }[]
  weights: {
    current: number
    proposed: number
  }
  counterexample: string
  blocks: Record<string, unknown>
}

Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Request

curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles

Requires bearerAuth

Selects a collector profile for the project, at revision 1. Human-only (org:admin): it adds every receiver of the profile. Nothing is installed; the profile is data a person applies in their own system.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  kind: "fly" | "serverless" | "render" | "vm" | "k8s_small"
  tier?: "minimal" | "standard"
  reason: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: 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}/infra/collector-profiles \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

PUT/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}

Requires bearerAuth

Parameters

Parameters for PUT /orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindrequiredpath"fly" | "serverless" | "render" | "vm" | "k8s_small"one of "fly" | "serverless" | "render" | "vm" | "k8s_small"

Request body (required) · application/json

{
  tier?: "minimal" | "standard"
  intervalSeconds?: integer
  excludedMetrics?: string[]
  restoreRevision?: integer
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: string
  }
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: 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 PUT https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind} \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}/config

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}/config
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindrequiredpath"fly" | "serverless" | "render" | "vm" | "k8s_small"one of "fly" | "serverless" | "render" | "vm" | "k8s_small"
distributionquery"otelcol-contrib" | "otelcol-k8s" | "alloy"one of "otelcol-contrib" | "otelcol-k8s" | "alloy"
rolequery"single" | "node" | "cluster"one of "single" | "node" | "cluster"

Response 200

{
  kind: "fly" | "serverless" | "render" | "vm" | "k8s_small"
  revision: integer
  profileId: string
  tier: "minimal" | "standard"
  intervalSeconds: integer
  files: {
    filename: string
    distribution: "otelcol-contrib" | "otelcol-k8s" | "alloy"
    role: "single" | "node" | "cluster"
    yaml: string
    components: 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}/projects/{projectSlug}/infra/collector-profiles/{kind}/config \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}/preview

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindrequiredpath"fly" | "serverless" | "render" | "vm" | "k8s_small"one of "fly" | "serverless" | "render" | "vm" | "k8s_small"

Request body (required) · application/json

{
  tier?: "minimal" | "standard"
  intervalSeconds?: integer
  excludedMetrics?: string[]
  restoreRevision?: integer
  reason?: string
  hours?: integer
}

Response 200

{
  kind: "fly" | "serverless" | "render" | "vm" | "k8s_small"
  revision: integer
  action: "narrow" | "widen" | "none"
  refusal: {
    code: string
    reason: string
  } | null
  projection: Record<string, unknown>
  change: Record<string, unknown>
  readers: Record<string, unknown>
  replay: Record<string, unknown> | null
  operation: {
    action: string
    class: string
    planDigest: string
  } | null
  operationNote: string | null
  counterexample: string
  trust: {
    untrustedFields: string[]
    note: 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}/infra/collector-profiles/{kind}/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}/widen

Requires bearerAuth

Widens a collector profile: adds a metric, shortens the interval, raises the tier or restores a wider retained revision. Human-only (org:admin); never an agent or an OAuth client.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/infra/collector-profiles/{kind}/widen
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindrequiredpath"fly" | "serverless" | "render" | "vm" | "k8s_small"one of "fly" | "serverless" | "render" | "vm" | "k8s_small"

Request body (required) · application/json

{
  tier?: "minimal" | "standard"
  intervalSeconds?: integer
  excludedMetrics?: string[]
  restoreRevision?: integer
  reason: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: 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}/infra/collector-profiles/{kind}/widen \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/digest

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/digest
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindquery"host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"one of "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
providerquerystringmin length 1, max length 200
environmentquerystringmin length 1, max length 200
servicequerystringmin length 1, max length 200
signalquery"metrics" | "logs" | "events" | "traces"one of "metrics" | "logs" | "events" | "traces"
statequery"live" | "lossy" | "stale" | "missing" | "unknown"one of "live" | "lossy" | "stale" | "missing" | "unknown"
includequerystringmax length 64
limitqueryintegermin 1, max 50
cursorquerystringmin length 1, max length 400

Response 200

{
  asOf: string
  counts: {
    total: integer
    projectTotal: integer
    byKind: {
      key: string
      count: integer
    }[]
    byProvider: {
      groups: object[]
      other: integer
      unset: integer
    }
    byEnvironment: {
      groups: object[]
      other: integer
      unset: integer
    }
  }
  stale: {
    count: integer
    oldest: {
      id: string
      kind: string
      ageSeconds: number
    }[]
  }
  coverageGaps: Record<string, {
    missing: integer
    stale: integer
    unknown: integer
  }>
  saturation: {
    status: "not_checked"
    source: string
    reason: string
  } | {
    status: "checked"
    basis: "metric_rollups_5m"
    catalogueVersion: integer
    threshold: {
      pct: integer
      saturatedPct: integer
      declared: boolean
    }
    windowDays: integer
    watermark: string
    more: boolean
    scope: "project"
    counts: {
      elevated: integer
      saturated: integer
      open: integer
    }
    facts: {
      windowId: string
      entityId: string
      resource: "memory" | "cpu" | "disk" | "oom" | "throttle"
      pair: string
      limitSource: "manifest" | "machine_size" | "platform_series"
      level: "elevated" | "saturated"
      state: "open" | "closed"
      startedAt: string
      endedAt: string | null
      peakRatio: number
      minutesSinceDeploy: integer | null
      statement: string
    }[]
  }
  changes: {
    windowHours: number
    total: integer
    byKind: {
      key: string
      count: integer
    }[]
    recent: {
      id: string
      kind: string
      occurredAt: string
      source: string | null
      trust: string
      environment: string | null
      service: string | null
      configSubject: string | null
      summary: string
    }[]
  }
  providerIncidents: {
    status: "not_checked"
    source: string
    reason: string
  } | {
    status: "checked"
    windowHours: number
    total: integer
    recent: {
      id: string
      kind: string
      occurredAt: string
      source: string | null
      trust: string
      environment: string | null
      service: string | null
      configSubject: string | null
      summary: string
    }[]
  }
  findings?: {
    status: "not_checked"
    source: string
    reason: string
  } | {
    status: "checked"
    asOf: string
    counts: {
      open: integer
      muted: integer
    }
    byRule: {
      rule: string
      open: integer
      muted: integer
    }[]
    rows: {
      id: string
      kind: string
      rule: string
      ruleVersion: integer
      state: "open" | "muted" | "resolved"
      entityId: string | null
      subject: string | null
      firstSeenAt: string
      lastSeenAt: string
      mutedUntil: string | null
      muteReason: string | null
      evidence: object
      proposedFix: object | null
      noFixReason: string | null
      formula: string | null
      costEffect: object | null
    }[]
    nextCursor: string | null
  }
  kubernetes?: {
    status: "not_checked"
    source: string
    reason: string
  } | {
    status: "checked"
    source: "k8sobjects"
    counts: {
      workloads: integer
      pods: integer
      nodes: integer
    }
    rollouts: {
      windowHours: number
      total: integer
      byState: object[]
      recent: object[]
    }
    ceiling: {
      limit: integer
      tracked: integer
      atCeiling: boolean
      overflow: object
    }
  }
  entities?: {
    rows: {
      id: string
      kind: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
      name: string
      provider: string | null
      environment: string | null
      service: string | null
      release: string | null
      ageSeconds: number
      seenAt: string
      firstSeenAt: string
      coverage: string
      saturated: "not_checked"
    }[]
    nextCursor: string | null
    previousServed: integer
    served: integer
    crossedExportThreshold: boolean
    capBit: "page_limit" | null
  }
  scanned: {
    entities: integer
    changes: integer
  }
  newestEntityAt: string | null
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    precedenceVersion: number
    fence?: {
      policyVersion: number
      scrubbed: number
      failedClosed: 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}/projects/{projectSlug}/infra/digest \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/entities

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/entities
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindquery"host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"one of "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
servicequerystringmin length 1, max length 200
environmentquerystringmin length 1, max length 200
signalquery"metrics" | "logs" | "events" | "traces"one of "metrics" | "logs" | "events" | "traces"
statequery"live" | "lossy" | "stale" | "missing" | "unknown"one of "live" | "lossy" | "stale" | "missing" | "unknown"
limitqueryintegermin 1, max 100
cursorquerystringmin length 1, max length 200

Response 200

{
  entities: {
    id: string
    kind: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
    identity: string
    displayName: string
    provider: string | null
    environment: string | null
    serviceName: string | null
    release: string | null
    aliases: string[]
    fields: Record<string, object>
    coverage: {
      metrics: object
      logs: object
      events: object
      traces: object
    }
    protected: boolean
    firstSeenAt: string
    lastSeenAt: string
  }[]
  nextCursor: string | null
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    precedenceVersion: number
    fence?: {
      policyVersion: number
      scrubbed: number
      failedClosed: 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}/projects/{projectSlug}/infra/entities \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/entities/{entityId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/entities/{entityId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
entityIdrequiredpathstringmin length 1, max length 64

Response 200

{
  entity: {
    id: string
    kind: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
    identity: string
    displayName: string
    provider: string | null
    environment: string | null
    serviceName: string | null
    release: string | null
    aliases: string[]
    fields: Record<string, object>
    coverage: {
      metrics: object
      logs: object
      events: object
      traces: object
    }
    protected: boolean
    firstSeenAt: string
    lastSeenAt: string
  }
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    precedenceVersion: number
    fence?: {
      policyVersion: number
      scrubbed: number
      failedClosed: 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}/projects/{projectSlug}/infra/entities/{entityId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/entities/{entityId}/detail

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/entities/{entityId}/detail
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
entityIdrequiredpathstringmin length 1, max length 64
includequerystringmax length 128

Response 200

{
  entity: {
    id: string
    kind: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
    identity: string
    displayName: string
    provider: string | null
    environment: string | null
    serviceName: string | null
    release: string | null
    aliases: string[]
    fields: Record<string, object>
    coverage: {
      metrics: object
      logs: object
      events: object
      traces: object
    }
    protected: boolean
    firstSeenAt: string
    lastSeenAt: string
  }
  blocks: {
    metrics?: {
      status: "checked"
      windowMinutes: number
      scanned: integer
      truncated: boolean
      names: integer
      series: object[]
      red: object
    }
    saturation?: {
      status: "not_checked"
      source: string
      reason: string
    } | {
      status: "checked"
      basis: "metric_rollups_5m"
      catalogueVersion: integer
      threshold: object
      windowDays: integer
      watermark: string
      more: boolean
      scope: "entity"
      facts: object[]
      limitUnknown: object[]
    }
    changes?: {
      status: "checked"
      windowDays: number
      items: object[]
      more: boolean
    }
    issues?: {
      status: "not_checked"
      source: string
      reason: string
    }
    findings?: {
      status: "not_checked"
      source: string
      reason: string
    } | {
      status: "checked"
      asOf: string
      counts: object
      byRule: object[]
      rows: object[]
      nextCursor: string | null
    }
    kubernetes?: {
      status: "not_checked"
      source: string
      reason: string
    } | {
      status: "checked"
      kind: "workload" | "pod" | "node"
      facts: object
      manifest: unknown
      manifestScrubbed: integer
      revisions?: object
      pods?: object
      rollouts?: object
    }
    coverage?: {
      status: "checked"
      code: string
      signals: object
    }
    config?: {
      status: "checked"
      aliases: string[]
      fields: object
    }
  }
  asOf: string
  scanned: {
    points: integer
    changes: integer
  }
  newestAt: string
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    precedenceVersion: number
    fence?: {
      policyVersion: number
      scrubbed: number
      failedClosed: 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}/projects/{projectSlug}/infra/entities/{entityId}/detail \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/findings

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/findings
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
kindquery"coverage" | "serverless_warning" | "rightsizing"one of "coverage" | "serverless_warning" | "rightsizing"
rulequerystringmin length 1, max length 64
entityquerystringmin length 1, max length 64
statequery"open" | "muted" | "resolved"one of "open" | "muted" | "resolved"
limitqueryintegermin 1, max 100
cursorquerystringmin length 1, max length 200

Response 200

{
  rows: {
    id: string
    kind: string
    rule: string
    ruleVersion: integer
    state: "open" | "muted" | "resolved"
    entityId: string | null
    subject: string | null
    firstSeenAt: string
    lastSeenAt: string
    mutedUntil: string | null
    muteReason: string | null
    evidence: Record<string, unknown>
    proposedFix: {
      summary: string
      steps: string[]
      change?: object
    } | null
    noFixReason: string | null
    formula: string | null
    costEffect: {
      amount: number
      currency: "USD"
      unit: "micro_usd_per_month"
      basis: string
      priceSource: string
    } | null
  }[]
  nextCursor: string | null
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    note: string
    fence?: {
      policyVersion: number | string
      scrubbed: integer
      failedClosed: 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}/projects/{projectSlug}/infra/findings \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/findings/{findingId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/findings/{findingId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
findingIdrequiredpathstring

Response 200

{
  finding: {
    id: string
    kind: string
    rule: string
    ruleVersion: integer
    state: "open" | "muted" | "resolved"
    entityId: string | null
    subject: string | null
    firstSeenAt: string
    lastSeenAt: string
    mutedUntil: string | null
    muteReason: string | null
    evidence: Record<string, unknown>
    proposedFix: {
      summary: string
      steps: string[]
      change?: object
    } | null
    noFixReason: string | null
    formula: string | null
    costEffect: {
      amount: number
      currency: "USD"
      unit: "micro_usd_per_month"
      basis: string
      priceSource: string
    } | null
  }
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    note: string
    fence?: {
      policyVersion: number | string
      scrubbed: integer
      failedClosed: 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}/projects/{projectSlug}/infra/findings/{findingId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/infra/findings/{findingId}/mute

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/infra/findings/{findingId}/mute
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
findingIdrequiredpathstring

Request body (required) · application/json

{
  ttlMinutes?: integer
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: string
  }
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: 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}/infra/findings/{findingId}/mute \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/infra/findings/{findingId}/unmute

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/infra/findings/{findingId}/unmute
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
findingIdrequiredpathstring

Request body (required) · application/json

{
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: string
  }
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  trust: {
    untrustedFields: string[]
    note: 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}/infra/findings/{findingId}/unmute \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/lever-bands

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/lever-bands
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Response 200

{
  bands: {
    entityId: string
    lever: "scale" | "restart"
    minReplicas: integer | null
    maxReplicas: integer | null
    setByPrincipalId: string | null
    updatedAt: string
  }[]
  note: 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}/infra/lever-bands \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/projects/{projectSlug}/infra/lever-bands

Requires bearerAuth

Parameters

Parameters for PUT /orgs/{orgSlug}/projects/{projectSlug}/infra/lever-bands
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  entityId: string
  lever: "scale" | "restart"
  minReplicas: integer | null
  maxReplicas: integer | null
  reason: string
}

Response 200

{
  status: "direct"
  action: "infra_lever_band.update"
  entityId: string
  lever: "scale" | "restart"
  before: {
    minReplicas: integer | null
    maxReplicas: integer | null
  }
  after: {
    minReplicas: integer | null
    maxReplicas: integer | null
  }
}

Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Request

curl -X PUT https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/infra/lever-bands \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/onboarding

Requires bearerAuth

The platforms this project runs on (connections, drains, span resource attributes, SDK language), and for a Collector platform the ready files from the selected profile revision. Reads only; the DSN appears as the name BUCKER_DSN, never its value.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/onboarding
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
valuesquery"0" | "1"one of "0" | "1"

Response 200

{
  platforms: Record<string, unknown>
}

Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.

{
  error: {
    code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
    message: string
    details?: unknown
    requestId?: string
  }
}

Request

curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/infra/onboarding \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/platform-webhooks

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/platform-webhooks
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Response 200

{
  platforms: {
    provider: "vercel" | "render" | "railway" | "heroku" | "netlify"
    url: string
    secretOrigin: "derived" | "entered"
    secret: string | null
    secretHeader: string | null
    entered: boolean | null
  }[]
  hasKey: 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}/projects/{projectSlug}/infra/platform-webhooks \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/infra/timeline

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/infra/timeline
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
environmentquerystringmin length 1, max length 128
servicequerystringmin length 1, max length 200
entityIdquerystringmin length 1, max length 128
releasequerystringmin length 1, max length 200
fromquerystring (date-time)
toquerystring (date-time)
cursorquerystringmin length 1, max length 600
lanesquerystringmax length 300
limitqueryintegermin 1, max 100

Response 200

{
  specVersion: integer
  window: {
    from: string
    to: string
  }
  lanes?: {
    lane: "issue_events" | "http_5xx" | "deploys" | "restarts_scale" | "rollbacks_mitigations" | "config_changes" | "provider_incidents" | "saturation" | … 2 more
    source: string
    status: "measured" | "not_measured"
    reason?: string
    freshness: string | null
    count: integer
    capped?: boolean
    notApplied?: string[]
  }[]
  items: {
    id: string
    lane: "issue_events" | "http_5xx" | "deploys" | "restarts_scale" | "rollbacks_mitigations" | "config_changes" | "provider_incidents" | "saturation" | … 2 more
    kind: string
    at: string
    endAt?: string | null
    state?: string
    summary?: string
    reference?: string
    environment?: string
    service?: string
    release?: string
    entityId?: string
    entityName?: string
    incident?: string
    provider?: string
    value?: number
    requests?: number
    serverErrors?: number
    resource?: string
    peakRatio?: number
    minutesSinceDeploy?: number | null
    rung?: string
    rungLabel?: string
    linkLabel?: string
    … 6 more
  }[]
  nextCursor: string | null
  newestAt: string | null
  trust: {
    level: "untrusted"
    untrustedFields: string[]
    fence?: {
      policyVersion: integer
      scrubbed: integer
      failedClosed: 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}/projects/{projectSlug}/infra/timeline \
  -H "authorization: Bearer $BUCKER_TOKEN"