Skip to content
bucker

API reference

public

Unauthenticated routes served to end users and integrations. 10 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.

GET/public/autonomy-scale

No declared credential scheme

Reachable without a Bucker session token. The published autonomy scale (ACP-30): one constant document derived from the rung vocabulary, no organization, project, agent or caller input, the same bytes for every request. Where an organization sits on the scale is autonomy_profile_get, behind its own relation.

Response 200

{
  version: string
  sha256: string
  rungs: string[]
  levels: {
    level: integer
    name: string
    rung: "RCA_ONLY" | "DRAFT_PR" | "AUTO_ATTEMPT" | null
    earned: boolean
    permits: string
    personDecides: string
  }[]
  neverMoves: {
    verbs: string[]
    objects: string[]
    statements: string[]
  }
  placement: string
  disclaimer: string
}

Response 304

No body.

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/public/autonomy-scale

GET/public/dashboard-snapshots/{token}

No declared credential scheme

Reachable without a Bucker session token. MET-24: the frozen render of ONE board that a person published; the unguessable, expiring, revocable token is the authorization (only its hash is stored), and the door charges a per-caller-address ceiling before the lookup.

Parameters

Parameters for GET /public/dashboard-snapshots/{token}
NameInTypeNotes
tokenrequiredpathstringmin length 1, max length 128

Response 200

Record<string, unknown>

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

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

Response 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/public/dashboard-snapshots/{token}

POST/public/enterprise-inquiries

No declared credential scheme

Reachable without a Bucker session token. The enterprise contact form on the public pricing page: the sender has no account. Rate limited per client address, field-bounded, honeypotted; read only through the operator console.

Request body (required) · application/json

{
  name: string
  email: string (email)
  company: string
  teamSize?: string
  term?: "monthly" | "annual" | "unsure"
  message: string
  website?: string
}

Response 202

{
  received: 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 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/public/enterprise-inquiries \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/public/insights/{token}

No declared credential scheme

Reachable without a Bucker session token. The floored numbers of one shared insight, by the bearer token of a published link or embed. Public: the token is the authorization. Read-only; a cell under the minimum cohort size is withheld; no node, id, project, organization or person is returned. An unknown, revoked, expired or archived link is a 404.

Parameters

Parameters for GET /public/insights/{token}
NameInTypeNotes
tokenrequiredpathstringmin length 1, max length 128

Response 200

{
  name: string
  kind: string
  range: {
    from: string
    to: string
  }
  result: "ok" | "no_data" | "tier_unavailable" | "held"
  reason: string | null
  data: Record<string, unknown> | null
  isApproximate: boolean
  approximation: string[]
  cohortFloor: {
    applied: boolean
    k: integer
  }
  expiresAt: 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 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/public/insights/{token}

GET/public/issue-shares/{token}

No declared credential scheme

Reachable without a Bucker session token. SG-161: a public link to one issue for a reader without a seat; the unguessable, expiring, revocable token is the authorization, and every read is audited.

Parameters

Parameters for GET /public/issue-shares/{token}
NameInTypeNotes
tokenrequiredpathstringmin length 8, max length 96

Response 200

{
  shortId: string
  title: string
  culprit: string | null
  level: string
  status: string
  exceptionType: string
  exceptionValue: {
    value: string
    trust: string
    flagged?: string
  }
  frames: {
    file: string
    function: string | null
    line: integer | null
    inApp: boolean
  }[]
  hiddenFrameCount: integer
  breadcrumbs: {
    kind: string
    text: {
      value: string
      trust: string
      flagged?: string
    }
    repeat: number
  }[]
  events: integer
  usersAffected: integer
  firstSeen: string
  lastSeen: string
  environments: string[]
  release: string | null
  securityNotice: string | null
  expiresAt: string
  disclosure: 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 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/public/issue-shares/{token}

POST/public/sandbox/guest-session

No declared credential scheme

Reachable without a Bucker session token. SG-111 "Try the live demo": mints a one-hour, org-pinned, read-only VIEWER session in the LOCKED sandbox org for a visitor with no account. Off until an operator sets the `sandbox:guest-sessions` ops flag; refuses any org not `readOnlySandbox`; rate limited per client address; audited as `auth.sandbox_guest.start`.

Request body (required) · application/json

{
  orgSlug?: string
}

Response 201

{
  accessToken: string
  tokenType: "Bearer"
  expiresIn: integer
  readOnly: true
  org: {
    id: string
    slug: string
    name: 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 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/public/sandbox/guest-session \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/public/status-pages/{orgSlug}/{pageSlug}/canonical-host

No declared credential scheme

Reachable without a Bucker session token. The reverse: the hostname the apex URL redirects to. Null for anything not public and served.

Parameters

Parameters for GET /public/status-pages/{orgSlug}/{pageSlug}/canonical-host
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
pageSlugrequiredpathstringmin length 1, max length 64

Response 200

{
  host: 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 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/public/status-pages/{orgSlug}/{pageSlug}/canonical-host

GET/public/status-pages/by-domain/{host}

No declared credential scheme

Reachable without a Bucker session token. Maps a verified customer hostname to its public page; the renderer asks before it can render.

Parameters

Parameters for GET /public/status-pages/by-domain/{host}
NameInTypeNotes
hostrequiredpathstringmin length 1, max length 263

Response 200

{
  orgSlug: string
  pageSlug: 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 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/public/status-pages/by-domain/{host}

GET/public/user-notices/unsubscribe

No declared credential scheme

Reachable without a Bucker session token. Signed token in the email footer; one-click unsubscribe cannot ask for a login, and the GET performs nothing (a link scanner must not opt anyone out).

Parameters

Parameters for GET /public/user-notices/unsubscribe
NameInTypeNotes
tokenrequiredquerystringmin length 10, max length 1000

Response 200

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 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/public/user-notices/unsubscribe

POST/public/user-notices/unsubscribe

No declared credential scheme

Reachable without a Bucker session token. RFC 8058 List-Unsubscribe-Post, from the mail client (and the page’s own button) — signed token.

Parameters

Parameters for POST /public/user-notices/unsubscribe
NameInTypeNotes
tokenrequiredquerystringmin length 10, max length 1000

Response 200

{
  ok: true
}

Response 400

{
  ok: false
}

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/public/user-notices/unsubscribe