Skip to content
bucker

API reference

analytics

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

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions

Requires bearerAuth

The project’s actions: key, name, the kinds of matcher, 30-day match counts (events and interactions, each row once; entries for a plain-event action) and what reads each (saved insights and metrics). Never a person, a selector or element text. Refused while product analytics is not enabled for the project.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
archivedquerybooleandefault false
daysqueryintegerdefault 30, min 1, max 90

Response 200

{
  items: {
    id: string
    key: string
    name: string
    description: string | null
    revision: integer
    archived: boolean
    matcherKinds: string[]
    matcherCount: integer
    matches: {
      window: object
      events: integer
      entries: integer | null
    } | null
    usedBy: {
      insights: integer
      metrics: integer
    }
  }[]
  total: integer
  limit: 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}/analytics/actions \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions

Requires bearerAuth

Create an action (analytics_action.create, a governed operation): a named set of at most ten matchers over custom events, page-view URLs, interaction-layer clicks and screen names, ORed across matchers and ANDed within one, applied retroactively to stored rollups. It changes no existing number: nothing reads it until an insight names it. A click selector that is a bare tag, a position, or unseen on the click stream in the last seven days makes the create ask a person. 202 input_required when a person must decide; retry with approvalRequestId.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  matchers?: {
    kind: "event"
    event: string
    where?: {
      property: string
      equals: string
    }
  } | {
    kind: "url"
    op: "equals" | "contains" | "route"
    value: string
    event?: string
    property?: string
  } | {
    kind: "click"
    selector?: string
    text?: string
    route?: string
  } | {
    kind: "screen"
    name: string
  }[]
  archive?: boolean
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: 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}/analytics/actions \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}

Requires bearerAuth

One action: its matchers, each matcher’s own count and status (a matcher on element text is not_stored, a URL matcher on an unpromoted property is property_not_promoted), the daily series, the selector checks against the last seven days, the revision history and what reads it. A plain-event action also carries entries, the entered count a funnel step on it would show.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
actionrequiredpathstringmin length 1, max length 64
daysqueryintegerdefault 30, min 1, max 90

Response 200

{
  id: string
  key: string
  name: string
  description: string | null
  revision: integer
  archived: boolean
  matcherKinds: string[]
  matcherCount: integer
  matches: {
    window: {
      from: string
      to: string
      days: integer
    }
    events: integer
    entries: integer | null
  } | null
  usedBy: {
    insights: integer
    metrics: integer
  }
  matchers: unknown[]
  fragility: {
    matcher: integer
    route: string | null
    leaf: string | null
    found: boolean
    clicks: integer
    fragile: "no_selector" | "bare_tag" | "positional" | "not_seen" | null
  }[]
  fragile: boolean
  matchDetail: {
    window: {
      from: string
      to: string
      days: integer
    }
    events: integer
    byDay: {
      day: string
      events: integer
    }[]
    matchers: {
      kind: string
      status: "counted" | "not_core" | "property_not_promoted" | "text_not_stored"
      events: integer | null
    }[]
    entries: integer | null
    subjectLevel: boolean
    notSubjectLevel: string[] | null
    approximation: string[]
    truncated: boolean
  } | null
  revisions: {
    revision: integer
    at: string
    authorPrincipalId: string | null
    changed: 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}/analytics/actions/{action} \
  -H "authorization: Bearer $BUCKER_TOKEN"

PATCH/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}

Requires bearerAuth

Change an action’s name, description or matchers, or archive or restore it (a governed operation: analytics_action.update, SENSITIVE and asked for; analytics_action.archive for an action nothing reads). The previous values are the inverse. There is no agent tool for this: an agent creates a new action and archives the old one. 202 input_required when a person must decide.

Parameters

Parameters for PATCH /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
actionrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  matchers?: {
    kind: "event"
    event: string
    where?: {
      property: string
      equals: string
    }
  } | {
    kind: "url"
    op: "equals" | "contains" | "route"
    value: string
    event?: string
    property?: string
  } | {
    kind: "click"
    selector?: string
    text?: string
    route?: string
  } | {
    kind: "screen"
    name: string
  }[]
  archive?: boolean
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: 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 PATCH https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action} \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}/delete

Requires bearerAuth

Delete an action. Human-only (a person on their own sign-in with org admin; an agent, an OAuth client or an organization token is refused) and irreversible: archive is the reversible path. A saved insight that names a deleted action fails with not found. The audit row lists what read the action as counts.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}/delete
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
actionrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  reason: string
}

Response 200

{
  key: string
  usedBy: {
    insights: integer
    metrics: integer
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}/preview

Requires bearerAuth

What an edit to an action would count and affect, without doing it: the counts the new matchers have right now and what reads the action (the saved insights and metrics whose numbers the edit could move). Writes nothing.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/{action}/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
actionrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  matchers?: {
    kind: "event"
    event: string
    where?: {
      property: string
      equals: string
    }
  } | {
    kind: "url"
    op: "equals" | "contains" | "route"
    value: string
    event?: string
    property?: string
  } | {
    kind: "click"
    selector?: string
    text?: string
    route?: string
  } | {
    kind: "screen"
    name: string
  }[]
  archive?: boolean
}

Response 200

{
  act: "create" | "update" | "archive"
  matches: {
    window: {
      from: string
      to: string
      days: integer
    }
    events: integer
    byDay: {
      day: string
      events: integer
    }[]
    matchers: {
      kind: string
      status: "counted" | "not_core" | "property_not_promoted" | "text_not_stored"
      events: integer | null
    }[]
    entries: integer | null
    subjectLevel: boolean
    notSubjectLevel: string[] | null
    approximation: string[]
    truncated: boolean
  }
  fragility: {
    matcher: integer
    fragile: "no_selector" | "bare_tag" | "positional" | "not_seen" | null
    found: boolean
    clicks: integer
  }[]
  selectorFragile: boolean
  usedBy: {
    insights: integer
    metrics: integer
  } | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/preview

Requires bearerAuth

What a new action would count over the last 30 days, without creating it: events and interactions per matcher, the union (each row once), entries for a plain-event action, and whether a click selector would make the create ask. Reads rollups; stores nothing and returns no person.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/actions/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  matchers?: {
    kind: "event"
    event: string
    where?: {
      property: string
      equals: string
    }
  } | {
    kind: "url"
    op: "equals" | "contains" | "route"
    value: string
    event?: string
    property?: string
  } | {
    kind: "click"
    selector?: string
    text?: string
    route?: string
  } | {
    kind: "screen"
    name: string
  }[]
  archive?: boolean
}

Response 200

{
  act: "create" | "update" | "archive"
  matches: {
    window: {
      from: string
      to: string
      days: integer
    }
    events: integer
    byDay: {
      day: string
      events: integer
    }[]
    matchers: {
      kind: string
      status: "counted" | "not_core" | "property_not_promoted" | "text_not_stored"
      events: integer | null
    }[]
    entries: integer | null
    subjectLevel: boolean
    notSubjectLevel: string[] | null
    approximation: string[]
    truncated: boolean
  }
  fragility: {
    matcher: integer
    fragile: "no_selector" | "bare_tag" | "positional" | "not_seen" | null
    found: boolean
    clicks: integer
  }[]
  selectorFragile: boolean
  usedBy: {
    insights: integer
    metrics: integer
  } | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations

Requires bearerAuth

The project’s annotations, newest first: notes pinned to the timeline (ChangeEvent ANNOTATION). With insightId, that insight’s own notes are listed beside the project’s; an insight the caller cannot see is not found. Archived notes are left out unless asked for. The text is untrusted: render it as text. Refused while product analytics is not enabled for the project.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
insightIdquerystringmin length 1, max length 64
fromquerystring (date-time)
toquerystring (date-time)
includeArchivedqueryboolean | "true" | "false"
limitqueryintegerdefault 25, min 1, max 100
cursorquerystringmin length 1, max length 512

Response 200

{
  data: {
    id: string
    text: string
    scope: "project" | "insight"
    insightId: string | null
    authorPrincipalId: string | null
    authorKind: string | null
    occurredAt: string
    createdAt: string
    archived: boolean
    trust: "untrusted"
  }[]
  nextCursor: string | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations

Requires bearerAuth

Add an annotation (annotation.create, a governed operation, ELEVATED and applied under ALLOW): a note of at most 2,000 characters, scrubbed and stored as ChangeEvent ANNOTATION, drawn on every chart of the project, or on one insight when scope is insight. It changes no number. The text is untrusted wherever it is read. 202 input_required when a person must decide; retry with approvalRequestId.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  text: string
  scope?: "project" | "insight"
  insightId?: string
  at?: string (date-time)
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  annotationId: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  annotationId: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: 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}/analytics/annotations \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations/{annotationId}/archive

Requires bearerAuth

Archive an annotation, or restore one archived within the last 90 days (annotation.archive, a governed operation). Your own annotation applies under ALLOW; another principal’s is SENSITIVE and asks, because it removes a marker other people and incident analysis read. An id that is not an annotation of this project is not found. There is no agent tool for this. 202 input_required when a person must decide.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations/{annotationId}/archive
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
annotationIdrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  archive?: boolean
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  annotationId: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  annotationId: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: 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}/analytics/annotations/{annotationId}/archive \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations/{annotationId}/delete

Requires bearerAuth

Delete an annotation permanently, for text that must not be kept. Human-only (a person on their own sign-in with org admin; an agent, an OAuth client or an organization token is refused) and irreversible: archive is the reversible path. The audit row names the scope and author, never the text.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/annotations/{annotationId}/delete
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
annotationIdrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  reason: string
}

Response 200

{
  id: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts

Requires bearerAuth

The project’s cohorts: key, name, kind, unit, status, the membership version served, its size floored at the minimum cohort size (null under it), when it was computed and what reads it (insights, alert rules, flags). Never a member. Refused while product analytics is not enabled for the project.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
archivedquerybooleandefault false

Response 200

{
  items: {
    id: string
    key: string
    name: string
    kind: "dynamic" | "static"
    unit: "subject" | "account"
    status: string
    version: integer
    count: integer | null
    belowFloor: boolean
    computedAt: string | null
    errorCount: integer
    usedBy: {
      insights: integer
      alertRules: integer
      flags: integer
      liveFlags: integer
    }
  }[]
  total: integer
  limit: integer
  floor: 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}/analytics/cohorts \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts

Requires bearerAuth

Create a cohort (cohort.create, a governed operation). A dynamic cohort takes a rule definition and is recomputed hourly from the rollups; a static cohort takes a data point (a funnel step’s droppers or completers, a retention cell, a breakdown value) and is computed once on the server. It lands as a draft: nothing reads it until its first membership version exists. A static cohort under the project’s minimum cohort size is refused. 202 input_required when a person must decide; retry with approvalRequestId.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  kind?: "dynamic" | "static"
  unit?: "subject" | "account"
  definition?: {
    v?: 1
    match?: "all" | "any"
    rules: {
      type: "performed"
      event: string
      within_days: integer
      min_times?: integer
      performed?: boolean
    } | {
      type: "sequence"
      events: string[]
      within_days: integer
      window_days?: integer
    } | {
      type: "property"
      key: string
      op: "eq" | "neq" | "in" | "not_in" | "exists" | "not_exists"
      value?: string
      values?: string[]
    } | {
      type: "lifecycle"
      event: string
      state: "first_time" | "regularly" | "stopped" | "restarted"
      within_days: integer
      min_days?: integer
    }[]
    account_type?: string
  }
  source?: {
    kind: "funnel_step"
    node: {
      v: 1
      range: object
      filters?: object[]
      exclude?: object
      identity?: "as_of_event" | "current"
      kind: "funnel"
      steps: object[]
      window: object
      order?: "ordered" | "unordered" | "strict"
      humans_only?: boolean
    }
    step: integer
    outcome: "droppers" | "completers"
  } | {
    kind: "retention_cell"
    event: string
    cohort_day: string
    period: integer
    unit?: "day" | "week"
    outcome: "returned" | "churned"
    lookback_days?: integer
  } | {
    kind: "breakdown_value"
    event: string
    range: {
      kind: "relative"
      last: integer
      unit: "day" | "week" | "month"
    } | {
      kind: "absolute"
      from: string
      to: string
    }
    property: string
    value: string
  }
  archive?: boolean
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  } | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  } | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}

Requires bearerAuth

One cohort: its definition (the closed rule grammar, or the data point a static cohort was computed from), the revision history with authors, the size of each membership version (floored) and what reads it. Never a member.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
cohortrequiredpathstringmin length 1, max length 64

Response 200

{
  id: string
  key: string
  name: string
  kind: "dynamic" | "static"
  unit: "subject" | "account"
  status: string
  version: integer
  count: integer | null
  belowFloor: boolean
  computedAt: string | null
  errorCount: integer
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  }
  description: string | null
  definition: unknown
  versions: {
    version: integer
    count: integer | null
    belowFloor: boolean
    reason: string
    at: string
    retained: boolean
  }[]
  revisions: {
    revision: integer
    at: string
    authorPrincipalId: string | null
    changed: string[]
  }[]
  oldestRetainedVersion: integer | null
  floor: 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}/analytics/cohorts/{cohort} \
  -H "authorization: Bearer $BUCKER_TOKEN"

PATCH/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}

Requires bearerAuth

Change a cohort’s name, description, definition or source, or archive or restore it (a governed operation: cohort.update, SENSITIVE and asked for; cohort.archive for a cohort nothing reads). The previous values are the inverse. When a live flag reads the cohort the change is floored at the flag audience class and never applies under an ALLOW row. A dynamic definition edit is recomputed by the next hourly pass; the previous membership is served meanwhile. 202 input_required when a person must decide.

Parameters

Parameters for PATCH /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
cohortrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  kind?: "dynamic" | "static"
  unit?: "subject" | "account"
  definition?: {
    v?: 1
    match?: "all" | "any"
    rules: {
      type: "performed"
      event: string
      within_days: integer
      min_times?: integer
      performed?: boolean
    } | {
      type: "sequence"
      events: string[]
      within_days: integer
      window_days?: integer
    } | {
      type: "property"
      key: string
      op: "eq" | "neq" | "in" | "not_in" | "exists" | "not_exists"
      value?: string
      values?: string[]
    } | {
      type: "lifecycle"
      event: string
      state: "first_time" | "regularly" | "stopped" | "restarted"
      within_days: integer
      min_days?: integer
    }[]
    account_type?: string
  }
  source?: {
    kind: "funnel_step"
    node: {
      v: 1
      range: object
      filters?: object[]
      exclude?: object
      identity?: "as_of_event" | "current"
      kind: "funnel"
      steps: object[]
      window: object
      order?: "ordered" | "unordered" | "strict"
      humans_only?: boolean
    }
    step: integer
    outcome: "droppers" | "completers"
  } | {
    kind: "retention_cell"
    event: string
    cohort_day: string
    period: integer
    unit?: "day" | "week"
    outcome: "returned" | "churned"
    lookback_days?: integer
  } | {
    kind: "breakdown_value"
    event: string
    range: {
      kind: "relative"
      last: integer
      unit: "day" | "week" | "month"
    } | {
      kind: "absolute"
      from: string
      to: string
    }
    property: string
    value: string
  }
  archive?: boolean
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  } | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  } | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}/delete

Requires bearerAuth

Delete a cohort with its membership versions. Human-only (a person on their own sign-in with org admin; an agent, an OAuth client or an organization token is refused), irreversible (archive is the reversible path), and refused while a live flag reads the cohort. The audit row lists what read it as counts.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}/delete
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
cohortrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  reason: string
}

Response 200

{
  key: string
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}/preview

Requires bearerAuth

What an edit to a cohort would hold and affect, without doing it: the size the new definition has right now (floored) and what reads the cohort, with the live flags that would raise the change’s class. Writes nothing and returns no member.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/{cohort}/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
cohortrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  kind?: "dynamic" | "static"
  unit?: "subject" | "account"
  definition?: {
    v?: 1
    match?: "all" | "any"
    rules: {
      type: "performed"
      event: string
      within_days: integer
      min_times?: integer
      performed?: boolean
    } | {
      type: "sequence"
      events: string[]
      within_days: integer
      window_days?: integer
    } | {
      type: "property"
      key: string
      op: "eq" | "neq" | "in" | "not_in" | "exists" | "not_exists"
      value?: string
      values?: string[]
    } | {
      type: "lifecycle"
      event: string
      state: "first_time" | "regularly" | "stopped" | "restarted"
      within_days: integer
      min_days?: integer
    }[]
    account_type?: string
  }
  source?: {
    kind: "funnel_step"
    node: {
      v: 1
      range: object
      filters?: object[]
      exclude?: object
      identity?: "as_of_event" | "current"
      kind: "funnel"
      steps: object[]
      window: object
      order?: "ordered" | "unordered" | "strict"
      humans_only?: boolean
    }
    step: integer
    outcome: "droppers" | "completers"
  } | {
    kind: "retention_cell"
    event: string
    cohort_day: string
    period: integer
    unit?: "day" | "week"
    outcome: "returned" | "churned"
    lookback_days?: integer
  } | {
    kind: "breakdown_value"
    event: string
    range: {
      kind: "relative"
      last: integer
      unit: "day" | "week" | "month"
    } | {
      kind: "absolute"
      from: string
      to: string
    }
    property: string
    value: string
  }
  archive?: boolean
}

Response 200

{
  act: "create" | "update" | "archive"
  kind: "dynamic" | "static"
  unit: "subject" | "account"
  size: {
    count: integer | null
    belowFloor: boolean
  }
  floor: integer
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  } | null
  refusal: {
    code: string
    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}/analytics/cohorts/{cohort}/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/preview

Requires bearerAuth

What a new cohort would hold, without creating it: its size right now, floored, and whether it would be refused (a static cohort under the floor, a cohort past the member bound). Evaluates the rollups; stores nothing and returns no member.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  key?: string
  name?: string
  description?: string | null
  kind?: "dynamic" | "static"
  unit?: "subject" | "account"
  definition?: {
    v?: 1
    match?: "all" | "any"
    rules: {
      type: "performed"
      event: string
      within_days: integer
      min_times?: integer
      performed?: boolean
    } | {
      type: "sequence"
      events: string[]
      within_days: integer
      window_days?: integer
    } | {
      type: "property"
      key: string
      op: "eq" | "neq" | "in" | "not_in" | "exists" | "not_exists"
      value?: string
      values?: string[]
    } | {
      type: "lifecycle"
      event: string
      state: "first_time" | "regularly" | "stopped" | "restarted"
      within_days: integer
      min_days?: integer
    }[]
    account_type?: string
  }
  source?: {
    kind: "funnel_step"
    node: {
      v: 1
      range: object
      filters?: object[]
      exclude?: object
      identity?: "as_of_event" | "current"
      kind: "funnel"
      steps: object[]
      window: object
      order?: "ordered" | "unordered" | "strict"
      humans_only?: boolean
    }
    step: integer
    outcome: "droppers" | "completers"
  } | {
    kind: "retention_cell"
    event: string
    cohort_day: string
    period: integer
    unit?: "day" | "week"
    outcome: "returned" | "churned"
    lookback_days?: integer
  } | {
    kind: "breakdown_value"
    event: string
    range: {
      kind: "relative"
      last: integer
      unit: "day" | "week" | "month"
    } | {
      kind: "absolute"
      from: string
      to: string
    }
    property: string
    value: string
  }
  archive?: boolean
}

Response 200

{
  act: "create" | "update" | "archive"
  kind: "dynamic" | "static"
  unit: "subject" | "account"
  size: {
    count: integer | null
    belowFloor: boolean
  }
  floor: integer
  usedBy: {
    insights: integer
    alertRules: integer
    flags: integer
    liveFlags: integer
  } | null
  refusal: {
    code: string
    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}/analytics/cohorts/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/floor

Requires bearerAuth

The project’s minimum cohort size: a cell of an analytics answer with fewer distinct subjects behind it is folded into other or shown as <k to every caller without the human-only pii:read. Also the revision (floorVersion), the default and the allowed range.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/floor
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Response 200

{
  minCohortSize: integer
  floorVersion: integer
  default: integer
  min: integer
  max: 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}/analytics/floor \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/projects/{projectSlug}/analytics/floor

Requires bearerAuth

Set the minimum cohort size (3 to 50). A raise is analytics_floor.narrow, a governed operation (202 input_required with the request to decide when a person must; retry with approvalRequestId). A lowering is analytics_floor.widen, human-only: a person on their own sign-in with org admin acts directly (200 direct) and the owners are alerted; an agent, an OAuth client or an organization token is refused. Which one it is follows from the figures, never from a flag.

Parameters

Parameters for PUT /orgs/{orgSlug}/projects/{projectSlug}/analytics/floor
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

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

Response 200

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  impact: {
    cells: integer
    direction: "folded" | "exposed" | "none"
  } | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft" | "direct"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  plan: Record<string, unknown> | null
  impact: {
    cells: integer
    direction: "folded" | "exposed" | "none"
  } | null
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/floor/preview

Requires bearerAuth

What a proposed minimum cohort size would do, without doing it: whether it is a raise (narrow) or a lowering (widen), and how many (event, breakdown value) series of the last 30 days it would newly fold or expose. Writes nothing.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/floor/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  minCohortSize: integer
}

Response 200

{
  from: integer
  to: integer
  act: "narrow" | "widen" | "none"
  impact: {
    cells: integer
    direction: "folded" | "exposed" | "none"
  }
  refusal: {
    code: string
    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}/analytics/floor/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights

Requires bearerAuth

Create a saved insight (a governed operation). With visibility draft (the default) it is a private draft of the caller and the agent acting for them: insight.draft, applied at once, gone after 90 days unless shared. With visibility shared it proposes sharing a new insight: insight.create, SENSITIVE and asked for, refused while the node’s trust check fails without a person’s override. 202 input_required when a person must decide; retry with approvalRequestId.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  node?: Record<string, unknown>
  name?: string | null
  description?: string | null
  visibility?: "draft" | "shared"
  promote?: integer
  archive?: boolean
  modelId?: string
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  insightShortId: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  insightShortId: 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}/analytics/insights \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

PATCH/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}

Requires bearerAuth

Change a saved insight (a governed operation; the act is read from the difference). Editing a draft is insight.draft. A new node on a shared insight writes a draft revision beside the served one and changes nothing readers see (insight.draft). visibility shared on a draft shares it (insight.create) and promote N serves revision N (insight.update); both are SENSITIVE and asked for, with the node, the compiled statement, the 30-day preview, the trust check, the materialisation cost and the boards that will show it. archive true archives (a shared insight asks); archive false restores within 90 days. 202 input_required when a person must decide.

Parameters

Parameters for PATCH /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  node?: Record<string, unknown>
  name?: string | null
  description?: string | null
  visibility?: "draft" | "shared"
  promote?: integer
  archive?: boolean
  modelId?: string
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  insightShortId: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  insightShortId: 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 PATCH https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight} \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/delete

Requires bearerAuth

Delete a shared insight with its revisions and links. Human-only (a person on their own sign-in with org admin; an agent, an OAuth client or an organization token is refused), irreversible (archive is the reversible path), and refused while an alert rule reads the insight. The audit row lists the boards that showed it as counts.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/delete
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  reason: string
}

Response 200

{
  shortId: string
  usedBy: {
    dashboards: integer
    alertRules: integer
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

Requires bearerAuth

The public links and embeds of a shared insight: when each ends, whether it is revoked and how often it was viewed. Never a token.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Response 200

{
  items: {
    id: string
    expiresAt: string
    revokedAt: string | null
    active: boolean
    createdAt: string
    createdByPrincipalId: string | null
    viewCount: integer
    lastViewedAt: string | null
  }[]
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links

Requires bearerAuth

Publish a link or an embed of a shared insight (insight.publish): anyone holding the link reads the floored numbers until it ends, at most 90 days. Human-only (a person on their own sign-in with org admin and a step-up; an agent, an OAuth client or an organization token is refused). The token is returned once.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  expiresInDays: integer
  stepUp?: {
    kind: "webauthn"
    nonce: string
    assertion: {
      credentialId: string
      clientDataJSON: string
      authenticatorData: string
      signature: string
    }
  } | {
    kind: "totp"
    code: string
  }
}

Response 200

{
  id: string
  token: string
  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 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}/analytics/insights/{insight}/links \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links/{link}/revoke

Requires bearerAuth

End a public link or embed (insight.revoke, ELEVATED, applied at once). It only narrows, so any holder of analytics:write, an agent included, may do it. Re-publishing is a person’s act.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links/{link}/revoke
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64
linkrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  insightShortId: string | null
}

Response 202

{
  status: "applied" | "input_required" | "inert_draft"
  action: string
  operationId: string | null
  planDigest: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionPath: string | null
  versionAfter: string | null
  insightShortId: 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}/analytics/insights/{insight}/links/{link}/revoke \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links/challenge

Requires bearerAuth

The step-up challenge a person answers to publish a link or an embed of a shared insight. Human-only: a person on their own sign-in with org admin.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links/challenge
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  expiresInDays: integer
}

Response 200

{
  requestId: string
  digest: string
  expiresAt: string
  methods: "webauthn" | "totp"[]
  webauthn: {
    challenge: string
    nonce: string
    rpId: string
    timeout: integer
    userVerification: "discouraged"
    allowCredentials: {
      type: "public-key"
      id: string
      transports: string[]
    }[]
  } | null
  enrolUrl: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/preview

Requires bearerAuth

What a change to a saved insight would do and what an approver would read: a draft edit, a share, a promotion, a rename or an archive. Give the same reason as the write: the plan, and so its digest, includes it. For a promotion this also records the engine’s preview of exactly that plan by you. Stores no insight change.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  node?: Record<string, unknown>
  name?: string | null
  description?: string | null
  visibility?: "draft" | "shared"
  promote?: integer
  archive?: boolean
  modelId?: string
  reason: string
}

Response 200

{
  act: string | null
  share: Record<string, unknown> | null
  trust: Record<string, unknown> | null
  changed: string[]
  refusal: {
    code: string
    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}/analytics/insights/{insight}/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/revisions

Requires bearerAuth

The revision ledger of a saved insight, newest first: each revision names the principal that wrote it and, for a governed change, the digest of the plan and the approval that covered it. A draft is visible to its author and the person the author acts for only.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/revisions
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64
insightrequiredpathstringmin length 1, max length 64

Response 200

{
  items: {
    revision: integer
    nodeHash: string
    planDigest: string | null
    approvalRequestId: string | null
    principalId: string | null
    reason: string | null
    createdAt: string
    served: 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}/analytics/insights/{insight}/revisions \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/preview

Requires bearerAuth

What a new insight would do and what an approver would read, without creating it: the act it would be, the compiled statement, the 30-day result preview (floored), the trust check, the materialisation cost and the boards that would show it. Runs the trust check when a share needs one and stores no insight.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  node?: Record<string, unknown>
  name?: string | null
  description?: string | null
  visibility?: "draft" | "shared"
  promote?: integer
  archive?: boolean
  modelId?: string
  reason: string
}

Response 200

{
  act: string | null
  share: Record<string, unknown> | null
  trust: Record<string, unknown> | null
  changed: string[]
  refusal: {
    code: string
    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}/analytics/insights/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/revert-preview

Requires bearerAuth

Record the engine’s preview of the stored inverse of an insight operation, so that operation_revert is accepted for it: the registry requires a preview of insight.update by the person who reverts, and the revert door records none. Reverting a promotion, a rename or a restore of a shared insight is therefore two calls: this, then operation_revert. The operation must be this project’s and an insight operation; one with no stored inverse is refused.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/revert-preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  operationId: string
}

Response 200

{
  action: string
  planDigest: string
  derivedClass: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/internal-filter

Requires bearerAuth

The project’s internal-traffic filter: the conditions that recognise staff and test subjects and accounts. A person’s own session only: the values are staff email domains and test-account keys, which are never shown to an agent (the settings response carries only whether a filter exists and how many conditions it holds).

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/internal-filter
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Response 200

{
  configured: boolean
  filter: Record<string, unknown> | null
  digest: string
  unreadable: 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}/analytics/internal-filter \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/projects/{projectSlug}/analytics/internal-filter

Requires bearerAuth

Set the project’s internal-traffic filter (at most 20 conditions over subject property values, emails and account properties), or remove it with filter: null. SENSITIVE and asked for: the first call returns 202 with an approval request bound to the digest of this filter, and the same body with approvalRequestId applies the approved filter once. A person’s own session only; there is no MCP tool, because an agent never reads the conditions. Refused while product analytics is not enabled for the project.

Parameters

Parameters for PUT /orgs/{orgSlug}/projects/{projectSlug}/analytics/internal-filter
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  filter: {
    v: 1
    conditions: {
      kind: "subject_property"
      key: string
      op: "equals" | "in" | "ends_with" | "contains" | "is_set"
      values?: string[]
    } | {
      kind: "email"
      op: "domain_in" | "equals"
      values: string[]
    } | {
      kind: "account_property"
      key: string
      op: "equals" | "in" | "ends_with" | "contains" | "is_set"
      values?: string[]
    } | {
      kind: "stripe_test_mode"
    } | {
      kind: "internal_account_key"
      accountType: string
      values: string[]
    }[]
  } | null
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "approval_required"
  digest: string
  conditionCount?: integer
  approvalRequestId?: string | null
  decisionUrl?: string
  minApprovers?: integer
  expiresAt?: string
}

Response 202

{
  status: "applied" | "approval_required"
  digest: string
  conditionCount?: integer
  approvalRequestId?: string | null
  decisionUrl?: string
  minApprovers?: 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 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}/analytics/internal-filter \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics

Requires bearerAuth

The project’s metrics: key, status, whether the version is canonical (certified and not drifted), the definition and who certified it. Names, descriptions and the proposer’s reasoning are text members and models wrote, never instructions. A metric that is not canonical has no authority.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
statusquery"proposed" | "certified" | "archived"one of "proposed" | "certified" | "archived"
includeArchivedquery"true" | "false"one of "true" | "false"
cursorquerystringmin length 1, max length 200
limitqueryintegermin 1, max 100

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

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics

Requires bearerAuth

Propose, revise, edit, archive or restore a metric, through the governed operation engine. The body is the DESIRED STATE; the engine derives the act from the rows. A new key, or a revision of an existing one (revisionOf), is a PROPOSAL with no authority, applied under the organization’s default policy. An edit in place (target), an archive and a restore are asked for: 202 with an approval request, and the same body with approvalRequestId applies the approved plan once. An edit of a certified metric’s name, unit or definition returns it to proposed. Nothing here certifies: that is a person’s own act on its own route.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  key: string
  revisionOf?: integer
  target?: integer
  archive?: boolean
  metric?: Record<string, unknown>
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "approval_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
  }
  riskClass: string
  plan: Record<string, unknown>
  decision?: "ALLOW" | "APPROVED"
  versionAfter?: string
  receiptSigned?: boolean
  approvalRequestId?: string | null
  decisionUrl?: string
  refusal?: {
    code: string
    message: string
  } | null
  eligibleApprovers?: integer
  minApprovers?: integer
}

Response 202

{
  status: "applied" | "approval_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
  }
  riskClass: string
  plan: Record<string, unknown>
  decision?: "ALLOW" | "APPROVED"
  versionAfter?: string
  receiptSigned?: boolean
  approvalRequestId?: string | null
  decisionUrl?: string
  refusal?: {
    code: string
    message: string
  } | null
  eligibleApprovers?: integer
  minApprovers?: integer
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}

Requires bearerAuth

Every version of one metric key, newest first, and the canonical one if there is one.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
keyrequiredpathstring

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}/analytics/metrics/{key} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify

Requires bearerAuth

Certify one metric version (metric_definition.certify): it becomes the canonical metric of its key, and a certified version it supersedes is archived in the same step. Human-only: refused to every agent, service, OAuth-client, delegated and derived credential, and to anyone without project admin. Needs the step-up bound to the previewed card (in production), refuses a drifted proposal, and signs a metric_certified receipt in the organization’s log.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
keyrequiredpathstring
versionrequiredpathintegermin 1, max 100000

Request body (required) · application/json

{
  previewDigest: string
  stepUp?: {
    kind: "webauthn"
    nonce: string
    assertion: {
      credentialId: string
      clientDataJSON: string
      authenticatorData: string
      signature: string
    }
  } | {
    kind: "totp"
    code: string
  }
}

Response 200

{
  key: string
  version: integer
  supersededVersion: integer | null
  definitionDigest: string
  certifiedAt: string
  receiptId: string
  previewDigest: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify/challenge

Requires bearerAuth

The step-up challenge a person answers to certify, bound to the digest of the card they are looking at. Human-only.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify/challenge
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
keyrequiredpathstring
versionrequiredpathintegermin 1, max 100000

Request body (required) · application/json

{
  previewDigest: string
}

Response 200

{
  requestId: string
  digest: string
  expiresAt: string
  methods: "webauthn" | "totp"[]
  webauthn: {
    challenge: string
    nonce: string
    rpId: string
    timeout: integer
    userVerification: "discouraged"
    allowCredentials: {
      type: "public-key"
      id: string
      transports: string[]
    }[]
  } | null
  enrolUrl: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify/challenge \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify/preview

Requires bearerAuth

The card a person reads before certifying one metric version: the definition, the field-by-field difference from the certified version it would supersede, the newest 90 days of values read as you (floored), the boards and alert rules that read it, the proposer’s words (untrusted), and the digest the step-up and the certification are bound to. Human-only: a person on their own session with project admin. Stores nothing.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
keyrequiredpathstring
versionrequiredpathintegermin 1, max 100000

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 -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/certify/preview \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/values

Requires bearerAuth

The newest 90 days of one metric version, read as you: the cohort floor, the budget and the project’s analytics gate apply, and a value that cannot be read says why instead of reading as zero.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/{key}/versions/{version}/values
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
keyrequiredpathstring
versionrequiredpathintegermin 1, max 100000

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}/analytics/metrics/{key}/versions/{version}/values \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/preview

Requires bearerAuth

What a metric write would do and what an approver would read, without doing it: the act the rows make it (a proposal, a revision, an edit in place, an archive, a restore), whether it demotes a certified metric, the readers it affects. Give the same reason as the write: the plan, and so its digest, includes it. Stores no metric.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  key: string
  revisionOf?: integer
  target?: integer
  archive?: boolean
  metric?: Record<string, unknown>
  reason: string
}

Response 200

{
  act: string
  key: string
  action: string
  planDigest: string
  derivedClass: string
  demotes: boolean
  plan: 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 -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/analytics/metrics/preview \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/trust-check

Requires bearerAuth

Run the trust check over the newest seven days of the data an insight reads and store the result: internal and test traffic (the project’s internal filter), development environments and localhost hosts, bots and automated browsers, duplicate uuids, ingest drops and sampled items, quarantined events, personless share and clock-skew corrections. Each line is pass, warn, fail or not_checked with counts and the rule version; a project with no internal filter reports not_checked, never pass. A fail blocks sharing the insight and alerting on it until a person overrides it. Name a node or a saved insight id. Refused while product analytics is not enabled for the project.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/trust-check
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  node?: Record<string, unknown>
  insightId?: string
}

Response 200

{
  ruleVersion: string
  nodeHash: string
  window: {
    from: string
    to: string
    days: integer
  }
  status: "pass" | "warn" | "fail"
  checks: {
    key: "internal_traffic" | "development_environments" | "localhost_hosts" | "bots" | "duplicate_uuids" | "ingest_drops" | "sampled_items" | "quarantined_events" | … 11 more
    outcome: "pass" | "warn" | "fail" | "not_checked"
    counts: Record<string, number | boolean | string | null>
    note: string | null
  }[]
  notChecked: "internal_traffic" | "development_environments" | "localhost_hosts" | "bots" | "duplicate_uuids" | "ingest_drops" | "sampled_items" | "quarantined_events" | … 11 more[]
  digest: string
  ranAt: string
  reused: boolean
  resultId: string | null
  subject: {
    kind: "node" | "insight"
    insightId: string | null
    events: string[]
    targets?: "web" | "revenue"[]
  }
}

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}/analytics/trust-check \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/trust-check/override

Requires bearerAuth

Accept a failing trust check for ONE node, with a reason and an end date (30 days by default, 90 at most). Human-only: a person’s own session holding project admin. Refused to every agent, service and OAuth-client credential, and no rung of the autonomy ladder reaches it. The node must have a stored failing check; name one failing line, or none for the whole check. Revoking it is the revoke route.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/trust-check/override
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  nodeHash: string
  checkKey?: "internal_traffic" | "development_environments" | "localhost_hosts" | "bots" | "duplicate_uuids" | "ingest_drops" | "sampled_items" | "quarantined_events" | … 11 more
  reason: string
  expiresAt?: string (date-time)
}

Response 200

{
  id: string
  nodeHash: string
  checkKey: string
  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 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}/analytics/trust-check/override \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

POST/orgs/{orgSlug}/projects/{projectSlug}/analytics/trust-check/override/revoke

Requires bearerAuth

Put the trust-check gate back on a node: revoke an override. Safety-increasing, so any member or agent holding analytics write may do it, and it applies under ALLOW unless the organization’s policy asks. Through the governed operation engine: 200 applied, 202 waiting for a person (retry the same body with approvalRequestId). Re-granting is a human act: the override route.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/analytics/trust-check/override/revoke
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  overrideId: string
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "approval_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
  }
  riskClass: string
  plan: Record<string, unknown>
  decision?: "ALLOW" | "APPROVED"
  versionAfter?: string
  receiptSigned?: boolean
  approvalRequestId?: string | null
  decisionUrl?: string
  refusal?: {
    code: string
    message: string
  } | null
  eligibleApprovers?: integer
  minApprovers?: integer
}

Response 202

{
  status: "applied" | "approval_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
  }
  riskClass: string
  plan: Record<string, unknown>
  decision?: "ALLOW" | "APPROVED"
  versionAfter?: string
  receiptSigned?: boolean
  approvalRequestId?: string | null
  decisionUrl?: string
  refusal?: {
    code: string
    message: string
  } | null
  eligibleApprovers?: integer
  minApprovers?: integer
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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