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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
archived | query | boolean | default false |
days | query | integer | default 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
actionrequired | path | string | min length 1, max length 64 |
days | query | integer | default 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
actionrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
actionrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
actionrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
insightId | query | string | min length 1, max length 64 |
from | query | string (date-time) | |
to | query | string (date-time) | |
includeArchived | query | boolean | "true" | "false" | |
limit | query | integer | default 25, min 1, max 100 |
cursor | query | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
annotationIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
annotationIdrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
archived | query | boolean | default 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
cohortrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
cohortrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
cohortrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
cohortrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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 '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/analytics/insights/{insight}/links
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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min length 1, max length 64 |
linkrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
insightrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
status | query | "proposed" | "certified" | "archived" | one of "proposed" | "certified" | "archived" |
includeArchived | query | "true" | "false" | one of "true" | "false" |
cursor | query | string | min length 1, max length 200 |
limit | query | integer | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
keyrequired | path | string |
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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
keyrequired | path | string | |
versionrequired | path | integer | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
keyrequired | path | string | |
versionrequired | path | integer | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
keyrequired | path | string | |
versionrequired | path | integer | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
keyrequired | path | string | |
versionrequired | path | integer | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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 '{ … }'