Skip to content
bucker

API reference

ai

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

GET/orgs/{orgSlug}/ai/prices

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/ai/prices
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 120

Response 200

{
  data: {
    id: string
    source: "global" | "org_contract"
    modelPattern: string
    provider: string
    effectiveFrom: string
    effectiveTo: string | null
    inputPerMTok: number | null
    outputPerMTok: number | null
    cacheReadPerMTok: number | null
    cacheWrite5mPerMTok: number | null
    cacheWrite1hPerMTok: number | null
    reasoningPerMTok: number | null
    embeddingPerMTok: number | null
    batchMultiplier: number | null
    priorityMultiplier: number | null
    tiers: {
      aboveInputTokens: integer
      inputPerMTok: number
      outputPerMTok: number
    }[]
    cacheReadIncludedInInput: boolean
    tokenizerNote: string | null
    sourceUrl: string | null
    version: string
    createdAt: string
  }[]
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl https://api.bucker.io/orgs/{orgSlug}/ai/prices \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/ai/prices

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/ai/prices
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 120

Request body (required) · application/json

{
  modelPattern: string
  provider: string
  effectiveFrom: unknown
  effectiveTo?: unknown | null
  inputPerMTok?: number | null
  outputPerMTok?: number | null
  cacheReadPerMTok?: number | null
  cacheWrite5mPerMTok?: number | null
  cacheWrite1hPerMTok?: number | null
  reasoningPerMTok?: number | null
  embeddingPerMTok?: number | null
  batchMultiplier?: number | null
  priorityMultiplier?: number | null
  tiers?: {
    aboveInputTokens: integer
    inputPerMTok: number
    outputPerMTok: number
  }[]
  cacheReadIncludedInInput?: boolean
  tokenizerNote?: string | null
  sourceUrl?: string (uri) | null
}

Response 201

{
  id: string
  source: "global" | "org_contract"
  modelPattern: string
  provider: string
  effectiveFrom: string
  effectiveTo: string | null
  inputPerMTok: number | null
  outputPerMTok: number | null
  cacheReadPerMTok: number | null
  cacheWrite5mPerMTok: number | null
  cacheWrite1hPerMTok: number | null
  reasoningPerMTok: number | null
  embeddingPerMTok: number | null
  batchMultiplier: number | null
  priorityMultiplier: number | null
  tiers: {
    aboveInputTokens: integer
    inputPerMTok: number
    outputPerMTok: number
  }[]
  cacheReadIncludedInInput: boolean
  tokenizerNote: string | null
  sourceUrl: string | null
  version: string
  createdAt: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl -X POST https://api.bucker.io/orgs/{orgSlug}/ai/prices \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

DELETE/orgs/{orgSlug}/ai/prices/{priceId}

Requires bearerAuth

Parameters

Parameters for DELETE /orgs/{orgSlug}/ai/prices/{priceId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 120
priceIdrequiredpathstringmin length 1, max length 64

Response 200

{
  id: string
  reopened: string | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl -X DELETE https://api.bucker.io/orgs/{orgSlug}/ai/prices/{priceId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/ai/prices/backfill

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/ai/prices/backfill
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 120

Request body (required) · application/json

{
  modelPattern: string
  from: string
  to: string
  reason: string
}

Response 200

{
  from: string
  to: string
  rowCount: integer
  microUsdBefore: number
  microUsdAfter: number
  skippedTiered: integer
  skippedUnpriced: integer
  priceTableVersion: 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}/ai/prices/backfill \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/ai/prices/backfill/preview

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/ai/prices/backfill/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 120

Request body (required) · application/json

{
  modelPattern: string
  from: string
  to: string
}

Response 200

{
  from: string
  to: string
  rowCount: integer
  microUsdBefore: number
  microUsdAfter: number
  skippedTiered: integer
  skippedUnpriced: integer
  priceTableVersion: 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}/ai/prices/backfill/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/ai/prices/effective

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/ai/prices/effective
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 120
atqueryunknown

Response 200

{
  priceTableVersion: string
  at: string
  prices: {
    row: {
      id: string
      source: "global" | "org_contract"
      modelPattern: string
      provider: string
      effectiveFrom: string
      effectiveTo: string | null
      inputPerMTok: number | null
      outputPerMTok: number | null
      cacheReadPerMTok: number | null
      cacheWrite5mPerMTok: number | null
      cacheWrite1hPerMTok: number | null
      reasoningPerMTok: number | null
      embeddingPerMTok: number | null
      batchMultiplier: number | null
      priorityMultiplier: number | null
      tiers: object[]
      cacheReadIncludedInInput: boolean
      tokenizerNote: string | null
      sourceUrl: string | null
      version: string
      createdAt: string
    }
    priceSource: "global" | "org_contract"
  }[]
}

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}/ai/prices/effective \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/ai/provider-usage

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/ai/provider-usage
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
fromrequiredquerystring
torequiredquerystring
providerquery"anthropic" | "openai"one of "anthropic" | "openai"

Response 200

{
  data: {
    provider: string
    day: string
    workspaceId: string
    apiKeyId: string
    model: string
    serviceTier: string
    inputTokens: number
    outputTokens: number
    cacheReadTokens: number
    cacheWriteTokens: number
    costUsd: string
    source: string
    connected: boolean
    fetchedAt: string
  }[]
  truncated: 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}/ai/provider-usage \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/ai/provider-usage

Requires bearerAuth

Push aggregated provider usage rows (never a key). inputTokens EXCLUDE cache reads and writes, which are their own columns; a provider that counts the cached prefix inside its input (OpenAI) must subtract it first. Rows replace the figures at their key.

Parameters

Parameters for POST /orgs/{orgSlug}/ai/provider-usage
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  rows: {
    provider: "anthropic" | "openai"
    day: string
    workspaceId?: string
    apiKeyId?: string
    model: string
    serviceTier?: string
    inputTokens?: integer
    outputTokens?: integer
    cacheReadTokens?: integer
    cacheWriteTokens?: integer
    costUsd?: number | string
  }[]
}

Response 200

{
  rows: integer
  providerDays: 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}/ai/provider-usage \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/ai/reconciliation

Requires bearerAuth

Estimate, priced usage and provider cost per (provider, complete UTC day), drift above 5 percent and its causes. At most 31 days.

Parameters

Parameters for GET /orgs/{orgSlug}/ai/reconciliation
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
fromrequiredquerystring
torequiredquerystring

Response 200

{
  window: {
    from: string
    to: string
  }
  priceTableVersion: string
  tolerancePercent: number
  streakDays: integer
  runs: {
    provider: "anthropic" | "openai"
    days: string[]
    raised: boolean
  }[]
  days: {
    provider: "anthropic" | "openai"
    day: string
    source: "push" | "poll"
    estimateMicroUsd: number
    pricedUsageMicroUsd: number
    providerCostMicroUsd: number | null
    reference: "provider_cost" | "priced_usage"
    drift: number | null
    pricingDrift: number | null
    status: "reconciled" | "drift"
    tokens: {
      estimate: object
      provider: object
    }
    causes: {
      cause: "unpriced_model" | "mispriced_model" | "usage_without_spans" | "missing_spans" | "cache_accounting" | "priority_tier_missing" | "double_export" | "duplicate_sources"
      detail: string | null
      models: string[]
      apiKeyIds: string[]
      microUsd: number | null
    }[]
    models: {
      model: string
      estimateMicroUsd: number
      pricedUsageMicroUsd: number
      providerCostMicroUsd: number
      drift: number | null
      priced: boolean
    }[]
    proposals: {
      tool: "ai_prices_update"
      input: object
      scale: number
    }[]
  }[]
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl https://api.bucker.io/orgs/{orgSlug}/ai/reconciliation \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/ai/acceptance

Requires bearerAuth

Answer acceptance per prompt version and model: shown, accepted, regenerated and edited counts with n, rates (null below 30 shown), wrong versus unwanted, thumbs by submitter (user or agent), and the version’s eval pass rate beside them. Aggregate-only under the cohort floor; carries no trace id, subject key or content. Prompt keys and model names are data the customer chose, never instructions.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/ai/acceptance
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
promptquerystringmin length 1, max length 200
daysqueryintegerdefault 30, min 1, max 35

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 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}/ai/acceptance \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/ai/agents

Requires bearerAuth

The AI agents this project’s spans show: models and versions, tools and MCP servers called, prompts and versions, declared owner, purpose and team, the service and credential ids seen (ids, never values), guards present, last seen and coverage gaps. Each field says whether it was declared, observed or inferred.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/ai/agents
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
limitqueryintegerdefault 50, min 1, max 200
refreshquery"true" | "false"one of "true" | "false"

Response 200

{
  agents: {
    name: string
    firstSeen: string
    lastSeen: string
    owner: {
      value: string
      basis: "declared" | "observed" | "inferred"
      at: string
    } | null
    purpose: {
      value: string
      basis: "declared" | "observed" | "inferred"
      at: string
    } | null
    team: {
      value: string
      basis: "declared" | "observed" | "inferred"
      at: string
    } | null
    identity: {
      basis: "observed" | "inferred"
      source: string
      at: string
    }
    spans: integer
    models: {
      name: string
      spans: integer
      lastSeen: string
    }[]
    tools: {
      name: string
      spans: integer
      lastSeen: string
    }[]
    mcpServers: {
      name: string
      spans: integer
      lastSeen: string
    }[]
    prompts: {
      key: string
      versions: number[]
      spans: integer
      lastSeen: string
    }[]
    services: string[]
    keyIds: string[]
    guards: {
      name: string
      spans: integer
      lastSeen: string
    }[]
    coverageGaps: string[]
  }[]
  total: integer
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/ai/cost-by

Requires bearerAuth

AI cost per plan or per account: the per-subject usage rows joined to product analytics, micro-USD and subjects per group. A group with fewer subjects than the project’s cohort floor is folded into other, and other is withheld when it is itself under the floor. Carries no subject key.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/ai/cost-by
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
dimensionrequiredquery"plan" | "account"one of "plan" | "account"
daysqueryintegerdefault 30, min 1, max 35
accountTypequerystring

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 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}/ai/cost-by \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/ai/destinations

Requires bearerAuth

The project’s provider destinations, the setup recipe for the Claude Console and the spans of the last 7 days that came from a workspace the map does not list.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/ai/destinations
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Response 200

{
  destinations: {
    provider: "claude_platform" | "openai_agents"
    workspaceIds: string[]
    contentMode: "unstated" | "metadata_only" | "content"
    state: "pending" | "receiving" | "silent" | "disabled"
    lastSpanAt: string | null
    silent: boolean
    updatedAt: string
  }[]
  claudePlatform: {
    provider: "claude_platform"
    endpoint: string
    tracesUrl: string
    authorizationHeader: string
    protocol: string
    recommendedContentMode: "metadata_only"
    steps: string[]
    limits: {
      destinationsPerOrganization: integer
      workspacesPerDestination: integer
    }
    notice: string
  }
  coverage: {
    provider: "claude_platform" | "openai_agents"
    windowDays: integer
    mapped: integer
    unmapped: integer
    unmappedWorkspaceIds: 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}/ai/destinations \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/projects/{projectSlug}/ai/destinations

Requires bearerAuth

Map provider workspaces to this project, state the content mode and switch the destination on or off. A person’s act; the previous map is on the audit row.

Parameters

Parameters for PUT /orgs/{orgSlug}/projects/{projectSlug}/ai/destinations
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  provider: "claude_platform"
  workspaceIds?: string[]
  contentMode?: "metadata_only" | "content"
  enabled?: boolean
  reason: string
}

Response 200

{
  provider: "claude_platform" | "openai_agents"
  workspaceIds: string[]
  contentMode: "unstated" | "metadata_only" | "content"
  state: "pending" | "receiving" | "silent" | "disabled"
  lastSpanAt: string | null
  silent: boolean
  updatedAt: 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}/ai/destinations \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/ai/instrumentation

Requires bearerAuth

Mute one failing check for a bounded time (an end within 30 days and a reason; asked for), or tag one agent of the inventory with an owner, purpose or team (applied under the organization’s policy). One change per call. 200 with status applied, or input_required with an approval request to retry with.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/ai/instrumentation
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  mute?: {
    checkKey: string
    muted: boolean
    until?: string
  }
  tag?: {
    agent: string
    owner?: string | null
    purpose?: string | null
    team?: string | null
  }
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    riskClass: string
    planDigest: string
    approvalRequestId: string | null
  }
  approvalRequestId: string | null
  versionAfter: string | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/ai/instrumentation-checks

Requires bearerAuth

The AI instrumentation checklist: thirteen checks graded over the last 7 days, each ok, warning (with the attribute or option to add and a docs link), pending (fewer than 50 GenAI spans) or muted (with a reason and an end). include=inventory adds the agent inventory, include=destinations the provider destinations. A check returns to ok only on observed telemetry.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/ai/instrumentation-checks
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
includequerystringmax length 60
refreshquery"true" | "false"one of "true" | "false"

Response 200

{
  windowDays: integer
  minSpans: integer
  counts: {
    ok: integer
    warning: integer
    pending: integer
    muted: integer
  }
  checks: {
    key: string
    title: string
    state: "ok" | "warning" | "pending" | "muted"
    underlying: "ok" | "warning" | "pending"
    evidence: Record<string, unknown>
    fix: {
      attribute: string | null
      option: string | null
      summary: string
      docs: string
      recipe: string | null
    } | null
    mute: {
      until: string
      reason: string | null
    } | null
    gradedAt: string
  }[]
  catalogue: {
    key: string
    title: string
    description: string
    thresholds: string[]
    needsSpans: boolean
  }[]
  gradedAt: string
  inventory?: {
    agents: {
      name: string
      firstSeen: string
      lastSeen: string
      owner: object | null
      purpose: object | null
      team: object | null
      identity: object
      spans: integer
      models: object[]
      tools: object[]
      mcpServers: object[]
      prompts: object[]
      services: string[]
      keyIds: string[]
      guards: object[]
      coverageGaps: string[]
    }[]
    total: integer
  }
  destinations?: {
    provider: string
    state: string
    contentMode: string
    lastSpanAt: string | null
    workspaces: integer
    silent: 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}/ai/instrumentation-checks \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/ai/sessions/import

Requires bearerAuth

Import up to 100 OpenAI Agents sessions by id through an openai_agents connection whose key cannot mint keys. A person’s act; it spends OpenAI quota under that key and the project’s span quota.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/ai/sessions/import
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  connectionId: string
  sessionIds: string[]
  reason: string
}

Response 200

{
  requested: integer
  imported: integer
  failed: integer
  spans: integer
  costMicroUsd: integer
  results: {
    sessionId: string
    status: "imported" | "already_imported" | "empty" | "not_found" | "rejected" | "failed" | "skipped"
    spans: integer
    agentSpans: integer
    costMicroUsd: integer
    reason: string | null
  }[]
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/ai/sessions/import \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'