Skip to content
bucker

API reference

accountability

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

GET/orgs/{orgSlug}/accountability/{principalId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/accountability/{principalId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
principalIdrequiredpathstringmin length 1
fromqueryunknown
toqueryunknown
actionClassquery"approval" | "remediation" | "agent_governance" | "issue" | "other"one of "approval" | "remediation" | "agent_governance" | "issue" | "other"
actionquerystringmin length 1, max length 120
agentIdquerystringmin length 1
projectIdquerystringmin length 1
outcomequery"APPROVAL" | "DECLINE" | "NEUTRAL"one of "APPROVAL" | "DECLINE" | "NEUTRAL"
attributionquery"DIRECT" | "DELEGATED" | "SPONSORED"one of "DIRECT" | "DELEGATED" | "SPONSORED"
cursorquerystringmin length 1, max length 500
limitqueryintegermin 1, max 200

Response 200

{
  org: {
    id: string
    slug: string
    name: string
  }
  subject: {
    principalId: string
    kind: "HUMAN" | "AGENT" | "SERVICE"
    displayName: string
    userId: string | null
    email: string | null
    orgRole: string
  }
  viewer: {
    principalId: string
    kind: "HUMAN" | "AGENT" | "SERVICE"
    displayName: string
  }
  isSelf: boolean
  window: {
    from: string | null
    to: string | null
  }
  summary: {
    actionsOnAuthority: number
    approvals: number
    declines: number
    neutral: number
    decisionRatio: {
      approvals: number
      declines: number
      ratio: number | null
      approvalRate: number | null
    }
    byAttribution: Record<string, number>
    byDeclineClass: Record<string, number>
    byActionClass: Record<string, number>
    sponsoredAgents: {
      id: string
      principalId: string
      name: string
      kind: string
      lifecycle: string
      maxTier: string
    }[]
    spendAttributed: {
      kind: string
      amount: number
      records: number
    }[]
    trustRungs: {
      agentId: string
      agentName: string
      category: string
      rung: string
      approvals: number
      rejections: number
      regressions: number
    }[]
  }
  entries: {
    auditLogId: string
    at: string
    action: string
    actionClass: "approval" | "remediation" | "agent_governance" | "issue" | "other"
    result: string
    outcome: "APPROVAL" | "DECLINE" | "NEUTRAL"
    declineClass: "HUMAN_REJECTION" | "POLICY_DENY" | "SELF_APPROVAL_BLOCKED" | "BUDGET_REFUSAL" | "EXPIRED" | "FORBIDDEN" | null
    attribution: "DIRECT" | "DELEGATED" | "SPONSORED"
    actor: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    onBehalfOf: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    agent: {
      id: string
      name: string
      kind: string
    } | null
    target: {
      type: string | null
      id: string | null
    }
    incidentId: string | null
    inputDigest: string | null
  }[]
  nextCursor: string | null
  projectFilterTruncated: 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}/accountability/{principalId} \
  -H 'authorization: Bearer $BUCKER_TOKEN'

GET/orgs/{orgSlug}/accountability/{principalId}/actions/{auditLogId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/accountability/{principalId}/actions/{auditLogId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
principalIdrequiredpathstringmin length 1
auditLogIdrequiredpathstringmin length 1

Response 200

{
  org: {
    id: string
    slug: string
    name: string
  }
  subject: {
    principalId: string
    kind: "HUMAN" | "AGENT" | "SERVICE"
    displayName: string
    userId: string | null
    email: string | null
    orgRole: string
  }
  entry: {
    auditLogId: string
    at: string
    action: string
    actionClass: "approval" | "remediation" | "agent_governance" | "issue" | "other"
    result: string
    outcome: "APPROVAL" | "DECLINE" | "NEUTRAL"
    declineClass: "HUMAN_REJECTION" | "POLICY_DENY" | "SELF_APPROVAL_BLOCKED" | "BUDGET_REFUSAL" | "EXPIRED" | "FORBIDDEN" | null
    attribution: "DIRECT" | "DELEGATED" | "SPONSORED"
    actor: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    onBehalfOf: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    agent: {
      id: string
      name: string
      kind: string
    } | null
    target: {
      type: string | null
      id: string | null
    }
    incidentId: string | null
    inputDigest: string | null
  }
  basis: {
    auditLogId: string
    at: string
    action: string
    actionClass: "approval" | "remediation" | "agent_governance" | "issue" | "other"
    result: string
    outcome: "APPROVAL" | "DECLINE" | "NEUTRAL"
    declineClass: "HUMAN_REJECTION" | "POLICY_DENY" | "SELF_APPROVAL_BLOCKED" | "BUDGET_REFUSAL" | "EXPIRED" | "FORBIDDEN" | null
    attribution: "DIRECT" | "DELEGATED" | "SPONSORED"
    subjectPrincipalId: string
    actor: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    onBehalfOf: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    agent: {
      agentId: string
      principalId: string
      name: string
      kind: string
      lifecycle: string
      maxTier: string
      sponsorUserId: string
    } | null
    delegation: {
      delegationId: string
      onBehalfOfUserId: string
      incidentId: string | null
      projectId: string | null
      scopes: string[]
      audience: string | null
      jti: string | null
      createdAt: string
      expiresAt: string
      revokedAt: string | null
      inForceAtAction: boolean
      matchedByJti: boolean
    } | null
    sponsor: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    budgets: {
      budgetId: string
      kind: string
      scopeKey: string
      limit: number
      consumed: number
      remaining: number
      period: string
    }[]
    trustLadder: {
      ladderId: string | null
      category: string
      rung: string
      implicit: boolean
      approvals: number
      rejections: number
      regressions: number
      consecutiveApprovals: number
    } | null
    approval: {
      approvalRequestId: string
      action: string
      riskClass: string
      status: string
      minApprovers: number
      requesterPrincipalId: string
      onBehalfOfPrincipalId: string | null
      deciderPrincipalId: string | null
      decidedAt: string | null
      policyId: string | null
    } | null
    verification: {
      proposalId: string
      runId: string
      issueId: string
      status: string
      verificationTier: string
      approvedByPrincipalId: string | null
      approvedAt: string | null
      rejectedByPrincipalId: string | null
      rejectedAt: string | null
      certificate: object | null
    } | null
    target: {
      type: string | null
      id: string | null
    }
    incidentId: string | null
    inputDigest: string | null
    gaps: {
      link: "actor" | "on_behalf_of" | "agent" | "delegation" | "sponsor" | "budget" | "trust_ladder" | "approval" | … 1 more
      reason: "MISSING" | "DELETED" | "EXPIRED" | "REVOKED" | "TRANSFERRED" | "UNBUDGETED"
      severity: "INFO" | "DEGRADED" | "BROKEN"
      detail: string
    }[]
    complete: 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}/accountability/{principalId}/actions/{auditLogId} \
  -H 'authorization: Bearer $BUCKER_TOKEN'

GET/orgs/{orgSlug}/accountability/{principalId}/export

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/accountability/{principalId}/export
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
principalIdrequiredpathstringmin length 1
fromqueryunknown
toqueryunknown
actionClassquery"approval" | "remediation" | "agent_governance" | "issue" | "other"one of "approval" | "remediation" | "agent_governance" | "issue" | "other"
actionquerystringmin length 1, max length 120
agentIdquerystringmin length 1
projectIdquerystringmin length 1
outcomequery"APPROVAL" | "DECLINE" | "NEUTRAL"one of "APPROVAL" | "DECLINE" | "NEUTRAL"
attributionquery"DIRECT" | "DELEGATED" | "SPONSORED"one of "DIRECT" | "DELEGATED" | "SPONSORED"
cursorquerystringmin length 1, max length 500
limitqueryintegermin 1, max 200

Response 200

{
  format: string
  algorithm: string
  signature: string
  documentHash: string
  document: {
    schema: string
    version: number
    generatedAt: string
    org: {
      id: string
      slug: string
      name: string
    }
    subject: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
      userId: string | null
      email: string | null
      orgRole: string
    }
    requestedBy: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    }
    window: {
      from: string | null
      to: string | null
    }
    filters: {
      actionClass: "approval" | "remediation" | "agent_governance" | "issue" | "other" | null
      action: string | null
      agentId: string | null
      projectId: string | null
      outcome: "APPROVAL" | "DECLINE" | "NEUTRAL" | null
      attribution: "DIRECT" | "DELEGATED" | "SPONSORED" | null
    }
    summary: {
      actionsOnAuthority: number
      approvals: number
      declines: number
      neutral: number
      decisionRatio: object
      byAttribution: object
      byDeclineClass: object
      byActionClass: object
      sponsoredAgents: object[]
      spendAttributed: object[]
      trustRungs: object[]
    }
    entryCount: number
    truncated: boolean
    entries: {
      auditLogId: string
      at: string
      action: string
      actionClass: "approval" | "remediation" | "agent_governance" | "issue" | "other"
      result: string
      outcome: "APPROVAL" | "DECLINE" | "NEUTRAL"
      declineClass: "HUMAN_REJECTION" | "POLICY_DENY" | "SELF_APPROVAL_BLOCKED" | "BUDGET_REFUSAL" | "EXPIRED" | "FORBIDDEN" | null
      attribution: "DIRECT" | "DELEGATED" | "SPONSORED"
      subjectPrincipalId: string
      actor: object | null
      onBehalfOf: object | null
      agent: object | null
      delegation: object | null
      sponsor: object | null
      budgets: object[]
      trustLadder: object | null
      approval: object | null
      verification: object | null
      target: object
      incidentId: string | null
      inputDigest: string | null
      gaps: object[]
      complete: 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}/accountability/{principalId}/export \
  -H 'authorization: Bearer $BUCKER_TOKEN'

GET/orgs/{orgSlug}/accountability/me

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/accountability/me
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
fromqueryunknown
toqueryunknown
actionClassquery"approval" | "remediation" | "agent_governance" | "issue" | "other"one of "approval" | "remediation" | "agent_governance" | "issue" | "other"
actionquerystringmin length 1, max length 120
agentIdquerystringmin length 1
projectIdquerystringmin length 1
outcomequery"APPROVAL" | "DECLINE" | "NEUTRAL"one of "APPROVAL" | "DECLINE" | "NEUTRAL"
attributionquery"DIRECT" | "DELEGATED" | "SPONSORED"one of "DIRECT" | "DELEGATED" | "SPONSORED"
cursorquerystringmin length 1, max length 500
limitqueryintegermin 1, max 200

Response 200

{
  org: {
    id: string
    slug: string
    name: string
  }
  subject: {
    principalId: string
    kind: "HUMAN" | "AGENT" | "SERVICE"
    displayName: string
    userId: string | null
    email: string | null
    orgRole: string
  }
  viewer: {
    principalId: string
    kind: "HUMAN" | "AGENT" | "SERVICE"
    displayName: string
  }
  isSelf: boolean
  window: {
    from: string | null
    to: string | null
  }
  summary: {
    actionsOnAuthority: number
    approvals: number
    declines: number
    neutral: number
    decisionRatio: {
      approvals: number
      declines: number
      ratio: number | null
      approvalRate: number | null
    }
    byAttribution: Record<string, number>
    byDeclineClass: Record<string, number>
    byActionClass: Record<string, number>
    sponsoredAgents: {
      id: string
      principalId: string
      name: string
      kind: string
      lifecycle: string
      maxTier: string
    }[]
    spendAttributed: {
      kind: string
      amount: number
      records: number
    }[]
    trustRungs: {
      agentId: string
      agentName: string
      category: string
      rung: string
      approvals: number
      rejections: number
      regressions: number
    }[]
  }
  entries: {
    auditLogId: string
    at: string
    action: string
    actionClass: "approval" | "remediation" | "agent_governance" | "issue" | "other"
    result: string
    outcome: "APPROVAL" | "DECLINE" | "NEUTRAL"
    declineClass: "HUMAN_REJECTION" | "POLICY_DENY" | "SELF_APPROVAL_BLOCKED" | "BUDGET_REFUSAL" | "EXPIRED" | "FORBIDDEN" | null
    attribution: "DIRECT" | "DELEGATED" | "SPONSORED"
    actor: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    onBehalfOf: {
      principalId: string
      kind: "HUMAN" | "AGENT" | "SERVICE"
      displayName: string
    } | null
    agent: {
      id: string
      name: string
      kind: string
    } | null
    target: {
      type: string | null
      id: string | null
    }
    incidentId: string | null
    inputDigest: string | null
  }[]
  nextCursor: string | null
  projectFilterTruncated: 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}/accountability/me \
  -H 'authorization: Bearer $BUCKER_TOKEN'