investigations
7 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.
GET/orgs/{orgSlug}/projects/{projectSlug}/investigations
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
rootKind | query | "issue" | "alert_event" | "correlation_group" | "change_event" | "metric_window" | "funnel_step" | "flag_change" | "check_run" | one of "issue" | "alert_event" | "correlation_group" | "change_event" | "metric_window" | "funnel_step" | "flag_change" | "check_run" |
rootId | query | string | min length 1, max length 128 |
trigger | query | "manual" | "alert" | "watcher" | "change_watch" | "playbook" | one of "manual" | "alert" | "watcher" | "change_watch" | "playbook" |
verdict | query | "concluded" | "inconclusive" | "abstained" | one of "concluded" | "inconclusive" | "abstained" |
status | query | "QUEUED" | "RUNNING" | "DONE" | "CANCELLED" | "FAILED" | one of "QUEUED" | "RUNNING" | "DONE" | "CANCELLED" | "FAILED" |
cursor | query | string | min length 1, max length 200 |
limit | query | integer | default 20, min 1, max 50 |
Response 200
{
data: {
id: string
orgId: string
projectId: string | null
root: {
kind: string | null
id: string | null
}
trigger: string
sourceKey: string | null
status: string
verdict: string | null
question: string
window: {
from: string
to: string
} | null
estimate: {
queries: integer
rowsScanned: integer
tokens: integer
cents: number
capCents: number
windowMinutes: integer
} | null
cost: {
cents: integer
tokens: integer
rowsScanned: integer
charged: boolean
}
startedByPrincipalId: string
inputs: {
id: string
input: object
principalId: string
at: string
}[]
createdAt: string
startedAt: string | null
completedAt: string | null
topCategory: string | null
}[]
nextCursor: string | null
counts: {
byVerdict: Record<string, integer>
byTrigger: Record<string, integer>
byRootKind: Record<string, integer>
}
sources: {
source: string
total: integer
concluded: integer
inconclusive: integer
abstained: integer
inconclusiveShare: number | null
medianSecondsToConclusion: number | 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}/investigations \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/investigations
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
Request body (required) · application/json
{
root: {
kind: "issue" | "alert_event" | "correlation_group" | "change_event" | "metric_window" | "funnel_step" | "flag_change" | "check_run"
id: string
}
question?: string
windowMinutes?: integer
}Response 202
{
investigation: {
id: string
orgId: string
projectId: string | null
root: {
kind: string | null
id: string | null
}
trigger: string
sourceKey: string | null
status: string
verdict: string | null
question: string
window: {
from: string
to: string
} | null
estimate: {
queries: integer
rowsScanned: integer
tokens: integer
cents: number
capCents: number
windowMinutes: integer
} | null
cost: {
cents: integer
tokens: integer
rowsScanned: integer
charged: boolean
}
startedByPrincipalId: string
inputs: {
id: string
input: object
principalId: string
at: string
}[]
result: {
mode: "investigation" | "evidence_pack"
stop: "RCA_ONLY" | null
infraClass: "host" | "kubernetes" | "network" | null
root: object
hypotheses: object[]
queries: object[]
evidence: object[]
conclusion: string
missingEvidence: string[]
steersApplied: string[]
excluded: string[]
passes: integer
rcaRunId: string | null
rcaNote: string | null
} | null
createdAt: string
startedAt: string | null
completedAt: string | null
}
estimate: {
queries: integer
rowsScanned: integer
tokens: integer
cents: number
capCents: number
windowMinutes: integer
}
riskClass: 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}/investigations \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/investigations/{investigationId}
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
investigationIdrequired | path | string | min length 1, max length 128 |
Response 200
{
id: string
orgId: string
projectId: string | null
root: {
kind: string | null
id: string | null
}
trigger: string
sourceKey: string | null
status: string
verdict: string | null
question: string
window: {
from: string
to: string
} | null
estimate: {
queries: integer
rowsScanned: integer
tokens: integer
cents: number
capCents: number
windowMinutes: integer
} | null
cost: {
cents: integer
tokens: integer
rowsScanned: integer
charged: boolean
}
startedByPrincipalId: string
inputs: {
id: string
input: Record<string, unknown>
principalId: string
at: string
}[]
result: {
mode: "investigation" | "evidence_pack"
stop: "RCA_ONLY" | null
infraClass: "host" | "kubernetes" | "network" | null
root: {
kind: string
id: string
title: string
at: string | null
}
hypotheses: {
id: string
category: string
statement: string
verdict: "validated" | "invalidated" | "inconclusive"
evidenceIds: string[]
queryDigests: string[]
missingEvidence: string[]
source: string
entityRef?: string
}[]
queries: {
label: string
specDigest: string
range: object
role: "window" | "baseline"
resultDigest: string
scanned: integer
result: string
value: number | null
evidenceId: string
variables?: object
}[]
evidence: {
id: string
kind: string
label: string
value?: number | null
}[]
conclusion: string
missingEvidence: string[]
steersApplied: string[]
excluded: string[]
passes: integer
rcaRunId: string | null
rcaNote: string | null
} | null
createdAt: string
startedAt: string | null
completedAt: 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}/investigations/{investigationId} \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/investigations/{investigationId}/cancel
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
investigationIdrequired | path | string | min length 1, max length 128 |
Response 200
{
id: string
orgId: string
projectId: string | null
root: {
kind: string | null
id: string | null
}
trigger: string
sourceKey: string | null
status: string
verdict: string | null
question: string
window: {
from: string
to: string
} | null
estimate: {
queries: integer
rowsScanned: integer
tokens: integer
cents: number
capCents: number
windowMinutes: integer
} | null
cost: {
cents: integer
tokens: integer
rowsScanned: integer
charged: boolean
}
startedByPrincipalId: string
inputs: {
id: string
input: Record<string, unknown>
principalId: string
at: string
}[]
result: {
mode: "investigation" | "evidence_pack"
stop: "RCA_ONLY" | null
infraClass: "host" | "kubernetes" | "network" | null
root: {
kind: string
id: string
title: string
at: string | null
}
hypotheses: {
id: string
category: string
statement: string
verdict: "validated" | "invalidated" | "inconclusive"
evidenceIds: string[]
queryDigests: string[]
missingEvidence: string[]
source: string
entityRef?: string
}[]
queries: {
label: string
specDigest: string
range: object
role: "window" | "baseline"
resultDigest: string
scanned: integer
result: string
value: number | null
evidenceId: string
variables?: object
}[]
evidence: {
id: string
kind: string
label: string
value?: number | null
}[]
conclusion: string
missingEvidence: string[]
steersApplied: string[]
excluded: string[]
passes: integer
rcaRunId: string | null
rcaNote: string | null
} | null
createdAt: string
startedAt: string | null
completedAt: 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}/investigations/{investigationId}/cancel \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/projects/{projectSlug}/investigations/{investigationId}/labels
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
investigationIdrequired | path | string | min length 1, max length 128 |
Response 200
{
current: {
id: string
investigationId: string
verdict: "right" | "wrong" | "partial"
trueCause: {
kind: string
entityRef: string
} | null
evidenceIds: string[]
note: {
value: string
trust: "untrusted" | "quarantined"
} | null
labelledByPrincipalId: string
labelledAt: string
current: boolean
snapshot: {
digest: string
state: "frozen" | "expired" | "unverified"
frozenAt: string | null
queries: object[] | null
}
} | null
history: {
id: string
investigationId: string
verdict: "right" | "wrong" | "partial"
trueCause: {
kind: string
entityRef: string
} | null
evidenceIds: string[]
note: {
value: string
trust: "untrusted" | "quarantined"
} | null
labelledByPrincipalId: string
labelledAt: string
current: boolean
snapshot: {
digest: string
state: "frozen" | "expired" | "unverified"
frozenAt: string | null
queries: object[] | 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}/investigations/{investigationId}/labels \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/investigations/{investigationId}/labels
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
investigationIdrequired | path | string | min length 1, max length 128 |
Request body (required) · application/json
{
verdict: "right" | "wrong" | "partial"
trueCause?: {
kind: "error_surge" | "release_regression" | "recent_change" | "service_errors" | "rca"
entityRef: string
}
evidenceIds?: string[]
note?: string
}Response 200
{
label: {
id: string
investigationId: string
verdict: "right" | "wrong" | "partial"
trueCause: {
kind: string
entityRef: string
} | null
evidenceIds: string[]
note: {
value: string
trust: "untrusted" | "quarantined"
} | null
labelledByPrincipalId: string
labelledAt: string
current: boolean
snapshot: {
digest: string
state: "frozen" | "expired" | "unverified"
frozenAt: string | null
queries: object[] | null
}
}
changed: boolean
}Response 201
{
label: {
id: string
investigationId: string
verdict: "right" | "wrong" | "partial"
trueCause: {
kind: string
entityRef: string
} | null
evidenceIds: string[]
note: {
value: string
trust: "untrusted" | "quarantined"
} | null
labelledByPrincipalId: string
labelledAt: string
current: boolean
snapshot: {
digest: string
state: "frozen" | "expired" | "unverified"
frozenAt: string | null
queries: object[] | null
}
}
changed: 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 -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/investigations/{investigationId}/labels \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/investigations/{investigationId}/steer
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 128 |
projectSlugrequired | path | string | min length 1, max length 128 |
investigationIdrequired | path | string | min length 1, max length 128 |
Request body (required) · application/json
{
inputs: Record<string, {
focus: "error_surge" | "release_regression" | "recent_change" | "service_errors" | "rca"
} | {
exclude: "error_surge" | "release_regression" | "recent_change" | "service_errors" | "rca"
} | {
hypothesis: object
} | {
extendWindow: integer
} | {
note: string
}>
}Response 200
{
id: string
orgId: string
projectId: string | null
root: {
kind: string | null
id: string | null
}
trigger: string
sourceKey: string | null
status: string
verdict: string | null
question: string
window: {
from: string
to: string
} | null
estimate: {
queries: integer
rowsScanned: integer
tokens: integer
cents: number
capCents: number
windowMinutes: integer
} | null
cost: {
cents: integer
tokens: integer
rowsScanned: integer
charged: boolean
}
startedByPrincipalId: string
inputs: {
id: string
input: Record<string, unknown>
principalId: string
at: string
}[]
result: {
mode: "investigation" | "evidence_pack"
stop: "RCA_ONLY" | null
infraClass: "host" | "kubernetes" | "network" | null
root: {
kind: string
id: string
title: string
at: string | null
}
hypotheses: {
id: string
category: string
statement: string
verdict: "validated" | "invalidated" | "inconclusive"
evidenceIds: string[]
queryDigests: string[]
missingEvidence: string[]
source: string
entityRef?: string
}[]
queries: {
label: string
specDigest: string
range: object
role: "window" | "baseline"
resultDigest: string
scanned: integer
result: string
value: number | null
evidenceId: string
variables?: object
}[]
evidence: {
id: string
kind: string
label: string
value?: number | null
}[]
conclusion: string
missingEvidence: string[]
steersApplied: string[]
excluded: string[]
passes: integer
rcaRunId: string | null
rcaNote: string | null
} | null
createdAt: string
startedAt: string | null
completedAt: 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}/investigations/{investigationId}/steer \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'