`transparency`

The public transparency register and its Merkle proofs. 8 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.

GET`/transparency/consistency-proof`

No declared credential scheme

Reachable without a Bucker session token. A proof an outsider cannot check is not a proof.

Parameters

Parameters for GET /transparency/consistency-proof
Name	In	Type	Notes
`oldSize`required	query	`integer`	min 0

Response 200

{
  oldSize: integer
  oldRoot: string
  newSize: integer
  newRoot: string
  proof: string[]
  verified: boolean
  disclosures: 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/transparency/consistency-proof

POST`/transparency/injection-trials`

Requires bearerAuth

Request body (required) · `application/json`

{
  campaignId: string
  mode: "SINGLE_ATTEMPT" | "ADAPTIVE"
  family?: string
  payload: string
}

Response 201

{
  id: string
  campaignId: string
  mode: "SINGLE_ATTEMPT" | "ADAPTIVE"
  attemptIndex: integer
  family: string
  payloadDigest: string
  evaded: boolean
  rule: string | null
  severity: string | null
  depth: integer | null
  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 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/transparency/injection-trials \
  -H 'authorization: Bearer $BUCKER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{ … }'

POST`/transparency/publish`

Requires bearerAuth

Request body (required) · `application/json`

{
  force?: boolean
}

Response 200

{
  snapshot: {
    id: string
    leafIndex: integer
    generatedAt: string
    digest: string
    leafHash: string
    rootHash: string
    treeSize: integer
    signature: string
    algorithm: string
    keyId: string
    publishedByPrincipalId: string | null
    register: {
      version: string
      generatedAt: string
      coverage: object
      rejectedPatches: object
      rejectionsByCategory: object[]
      regressionsCausedByOurFixes: object
      regressionKinds: object[]
      firstAttemptFailureOverall: object
      firstAttemptFailureByLanguage: object[]
      injection: object
      notMeasured: string[]
      provenanceNote: string
      suppression: object
      disclosures: string[]
    }
  }
  unchanged: boolean
  disclosures: 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 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/transparency/publish \
  -H 'authorization: Bearer $BUCKER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{ … }'

GET`/transparency/register`

No declared credential scheme

Reachable without a Bucker session token. Transparency register read — deliberately public.

Response 200

{
  version: string
  generatedAt: string
  coverage: {
    firstObservationAt: string | null
    lastObservationAt: string | null
  }
  rejectedPatches: {
    label: string
    definition: string
    sources: string[]
    numerator: integer
    denominator: integer
    rate: number | null
    confidence: {
      lower: number
      upper: number
      level: number
    } | null
    sufficient: boolean
    publishable: boolean
    statement: string
  }
  rejectionsByCategory: {
    category: string
    count: integer
  }[]
  regressionsCausedByOurFixes: {
    label: string
    definition: string
    sources: string[]
    numerator: integer
    denominator: integer
    rate: number | null
    confidence: {
      lower: number
      upper: number
      level: number
    } | null
    sufficient: boolean
    publishable: boolean
    statement: string
  }
  regressionKinds: {
    kind: string
    count: integer
  }[]
  firstAttemptFailureOverall: {
    label: string
    definition: string
    sources: string[]
    numerator: integer
    denominator: integer
    rate: number | null
    confidence: {
      lower: number
      upper: number
      level: number
    } | null
    sufficient: boolean
    publishable: boolean
    statement: string
  }
  firstAttemptFailureByLanguage: {
    label: string
    definition: string
    sources: string[]
    numerator: integer
    denominator: integer
    rate: number | null
    confidence: {
      lower: number
      upper: number
      level: number
    } | null
    sufficient: boolean
    publishable: boolean
    statement: string
    language: string
  }[]
  injection: {
    singleAttempt: {
      label: string
      definition: string
      sources: string[]
      numerator: integer
      denominator: integer
      rate: number | null
      confidence: object | null
      sufficient: boolean
      publishable: boolean
      statement: string
    }
    adaptiveCampaign: {
      label: string
      definition: string
      sources: string[]
      numerator: integer
      denominator: integer
      rate: number | null
      confidence: object | null
      sufficient: boolean
      publishable: boolean
      statement: string
    }
    adaptivePerAttempt: {
      label: string
      definition: string
      sources: string[]
      numerator: integer
      denominator: integer
      rate: number | null
      confidence: object | null
      sufficient: boolean
      publishable: boolean
      statement: string
    }
    campaigns: {
      single: integer
      adaptive: integer
    }
    note: string
  }
  notMeasured: string[]
  provenanceNote: string
  suppression: {
    available: false
    note: string
  }
  disclosures: 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/transparency/register

GET`/transparency/snapshots`

No declared credential scheme

Reachable without a Bucker session token. Transparency register read — deliberately public.

Parameters

Parameters for GET /transparency/snapshots
Name	In	Type	Notes
`limit`	query	`integer`	default 50, min 1, max 200

Response 200

{
  treeSize: integer
  rootHash: string
  snapshots: {
    id: string
    leafIndex: integer
    generatedAt: string
    digest: string
    rootHash: string
    treeSize: integer
    keyId: string
  }[]
  disclosures: 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/transparency/snapshots

GET`/transparency/snapshots/{leafIndex}`

No declared credential scheme

Reachable without a Bucker session token. Transparency register read — deliberately public.

Parameters

Parameters for GET /transparency/snapshots/{leafIndex}
Name	In	Type	Notes
`leafIndex`required	path	`integer`	min 0

Response 200

{
  snapshot: {
    id: string
    leafIndex: integer
    generatedAt: string
    digest: string
    leafHash: string
    rootHash: string
    treeSize: integer
    signature: string
    algorithm: string
    keyId: string
    publishedByPrincipalId: string | null
    register: {
      version: string
      generatedAt: string
      coverage: object
      rejectedPatches: object
      rejectionsByCategory: object[]
      regressionsCausedByOurFixes: object
      regressionKinds: object[]
      firstAttemptFailureOverall: object
      firstAttemptFailureByLanguage: object[]
      injection: object
      notMeasured: string[]
      provenanceNote: string
      suppression: object
      disclosures: string[]
    }
  }
  disclosures: 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/transparency/snapshots/{leafIndex}

GET`/transparency/snapshots/{leafIndex}/audit`

No declared credential scheme

Reachable without a Bucker session token. A proof an outsider cannot check is not a proof.

Parameters

Parameters for GET /transparency/snapshots/{leafIndex}/audit
Name	In	Type	Notes
`leafIndex`required	path	`integer`	min 0

Response 200

{
  leafIndex: integer
  valid: boolean
  failures: {
    code: string
    message: string
  }[]
  disclosures: 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/transparency/snapshots/{leafIndex}/audit

GET`/transparency/snapshots/{leafIndex}/inclusion-proof`

No declared credential scheme

Reachable without a Bucker session token. A proof an outsider cannot check is not a proof.

Parameters

Parameters for GET /transparency/snapshots/{leafIndex}/inclusion-proof
Name	In	Type	Notes
`leafIndex`required	path	`integer`	min 0
`treeSize`	query	`integer`	min 1

Response 200

{
  leafIndex: integer
  leafHash: string
  treeSize: integer
  rootHash: string
  proof: string[]
  verified: boolean
  disclosures: 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/transparency/snapshots/{leafIndex}/inclusion-proof

transparency

GET/transparency/consistency-proof

Parameters

Response 200

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

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.

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

Request

POST/transparency/injection-trials

Request body (required) · application/json

Response 201

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

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.

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.

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.

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

Request

POST/transparency/publish

Request body (required) · application/json

Response 200

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

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.

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.

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.

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

Request

GET/transparency/register

Response 200

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.

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

Request

GET/transparency/snapshots

Parameters

Response 200

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

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.

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

Request

GET/transparency/snapshots/{leafIndex}

Parameters

Response 200

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

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.

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.

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

Request

GET/transparency/snapshots/{leafIndex}/audit

Parameters

Response 200

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

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.

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.

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

Request

GET/transparency/snapshots/{leafIndex}/inclusion-proof

Parameters

Response 200

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

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.

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.

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

Request

`transparency`

GET`/transparency/consistency-proof`

POST`/transparency/injection-trials`

Request body (required) · `application/json`

POST`/transparency/publish`

Request body (required) · `application/json`

GET`/transparency/register`

GET`/transparency/snapshots`

GET`/transparency/snapshots/{leafIndex}`

GET`/transparency/snapshots/{leafIndex}/audit`

GET`/transparency/snapshots/{leafIndex}/inclusion-proof`