Skip to content
bucker

API reference

views

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

GET/orgs/{orgSlug}/views

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/views
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
projectSlugquerystringmin length 1, max length 64
surfacequery"issues" | "explore" | "logs" | "replays" | "infra" | "metrics" | "web"default "issues", one of "issues" | "explore" | "logs" | "replays" | "infra" | "metrics" | "web"
streamquery"org"one of "org"

Response 200

{
  data: {
    id: string
    orgId: string
    projectId: string | null
    ownerPrincipalId: string
    name: string
    slug: string | null
    filter: {
      state: object
      columns: object
    }
    surface: "issues" | "explore" | "logs" | "replays" | "infra" | "metrics" | "web"
    query: {
      kind: "explore"
      query: object
    } | {
      kind: "logs"
      state: object
    } | {
      kind: "replays"
      state: object
    } | {
      kind: "infra"
      state: object
    } | {
      kind: "web"
      state: object
    } | null
    visibility: "PRIVATE" | "ORG"
    pinned: boolean
    editable: boolean
    starred: boolean
    createdAt: string
    updatedAt: string
  }[]
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

POST/orgs/{orgSlug}/views

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/views
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  name: string
  projectSlug?: string
  filter?: {
    state: {
      query?: string
      environment?: string
      release?: string
      assignee?: string
      status?: "NEW" | "ONGOING" | "RESOLVED" | "ARCHIVED" | "REGRESSED"[]
      level?: "fatal" | "error" | "warning" | "info" | "debug"[]
      sort?: "lastSeen" | "firstSeen" | "eventCount" | "userCount" | "priority" | "actionability" | "revenueAtRisk" | "accountsAffected"
      order?: "asc" | "desc"
      hours?: integer | null
      priority?: "HIGH" | "MEDIUM" | "LOW"[]
    }
    columns?: Record<string, boolean>
  }
  visibility?: "PRIVATE" | "ORG"
  pinned?: boolean
  surface?: "issues" | "explore" | "logs" | "replays" | "infra" | "metrics" | "web"
  query?: {
    kind: "explore"
    query: {
      dataset?: "spans" | "logs" | "events" | "metrics" | "survey_answers"
      fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
      field?: string
      groupBy?: string
      filters?: object[]
      sameTrace?: object
      limit?: integer
      intervalMinutes?: integer
      hours?: integer
    }
  } | {
    kind: "logs"
    state: {
      q?: string
      severity?: "trace" | "debug" | "info" | "warn" | "error" | "fatal"[]
      environment?: string
      traceId?: string
      hours?: integer
      pinned?: string[]
    }
  } | {
    kind: "replays"
    state: {
      query?: string
      sort?: "newest" | "oldest" | "errors" | "rage_clicks" | "duration" | "notable"
      hideViewed?: boolean
    }
  } | {
    kind: "infra"
    state: {
      kind?: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
      provider?: string
      environment?: string
      service?: string
      signal?: "metrics" | "logs" | "events" | "traces"
      state?: "live" | "lossy" | "stale" | "missing" | "unknown"
    }
  } | {
    kind: "web"
    state: {
      days?: integer
      dimension?: "page" | "entry" | "exit" | "referrer" | "utm_source" | "utm_medium" | "utm_campaign" | "utm_term" | … 8 more
      segment?: object
      include?: "attribution"[]
    }
  }
}

Response 201

{
  id: string
  orgId: string
  projectId: string | null
  ownerPrincipalId: string
  name: string
  slug: string | null
  filter: {
    state: {
      query: string
      environment: string
      release: string
      assignee: string
      status: "NEW" | "ONGOING" | "RESOLVED" | "ARCHIVED" | "REGRESSED"[]
      level: "fatal" | "error" | "warning" | "info" | "debug"[]
      sort: "lastSeen" | "firstSeen" | "eventCount" | "userCount" | "priority" | "actionability" | "revenueAtRisk" | "accountsAffected"
      order: "asc" | "desc"
      hours: integer | null
      priority: "HIGH" | "MEDIUM" | "LOW"[]
    }
    columns: Record<string, boolean>
  }
  surface: "issues" | "explore" | "logs" | "replays" | "infra" | "metrics" | "web"
  query: {
    kind: "explore"
    query: {
      dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
      fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
      field?: string
      groupBy?: string
      filters: object[]
      sameTrace?: object
      limit?: integer
      intervalMinutes?: integer
      hours?: integer
    }
  } | {
    kind: "logs"
    state: {
      q: string
      severity: "trace" | "debug" | "info" | "warn" | "error" | "fatal"[]
      environment: string
      traceId: string
      hours: integer
      pinned: string[]
    }
  } | {
    kind: "replays"
    state: {
      query: string
      sort: "newest" | "oldest" | "errors" | "rage_clicks" | "duration" | "notable"
      hideViewed: boolean
    }
  } | {
    kind: "infra"
    state: {
      kind?: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
      provider?: string
      environment?: string
      service?: string
      signal?: "metrics" | "logs" | "events" | "traces"
      state?: "live" | "lossy" | "stale" | "missing" | "unknown"
    }
  } | {
    kind: "web"
    state: {
      days: integer
      dimension?: "page" | "entry" | "exit" | "referrer" | "utm_source" | "utm_medium" | "utm_campaign" | "utm_term" | … 8 more
      segment?: object
      include?: "attribution"[]
    }
  } | null
  visibility: "PRIVATE" | "ORG"
  pinned: boolean
  editable: boolean
  starred: boolean
  createdAt: string
  updatedAt: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

DELETE/orgs/{orgSlug}/views/{viewId}

Requires bearerAuth

Parameters

Parameters for DELETE /orgs/{orgSlug}/views/{viewId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
viewIdrequiredpathstringmin length 1, max length 64

Response 204

No body.

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

PATCH/orgs/{orgSlug}/views/{viewId}

Requires bearerAuth

Parameters

Parameters for PATCH /orgs/{orgSlug}/views/{viewId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
viewIdrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  name?: string
  filter?: {
    state: {
      query?: string
      environment?: string
      release?: string
      assignee?: string
      status?: "NEW" | "ONGOING" | "RESOLVED" | "ARCHIVED" | "REGRESSED"[]
      level?: "fatal" | "error" | "warning" | "info" | "debug"[]
      sort?: "lastSeen" | "firstSeen" | "eventCount" | "userCount" | "priority" | "actionability" | "revenueAtRisk" | "accountsAffected"
      order?: "asc" | "desc"
      hours?: integer | null
      priority?: "HIGH" | "MEDIUM" | "LOW"[]
    }
    columns?: Record<string, boolean>
  }
  visibility?: "PRIVATE" | "ORG"
  pinned?: boolean
  query?: {
    kind: "explore"
    query: {
      dataset?: "spans" | "logs" | "events" | "metrics" | "survey_answers"
      fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
      field?: string
      groupBy?: string
      filters?: object[]
      sameTrace?: object
      limit?: integer
      intervalMinutes?: integer
      hours?: integer
    }
  } | {
    kind: "logs"
    state: {
      q?: string
      severity?: "trace" | "debug" | "info" | "warn" | "error" | "fatal"[]
      environment?: string
      traceId?: string
      hours?: integer
      pinned?: string[]
    }
  } | {
    kind: "replays"
    state: {
      query?: string
      sort?: "newest" | "oldest" | "errors" | "rage_clicks" | "duration" | "notable"
      hideViewed?: boolean
    }
  } | {
    kind: "infra"
    state: {
      kind?: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
      provider?: string
      environment?: string
      service?: string
      signal?: "metrics" | "logs" | "events" | "traces"
      state?: "live" | "lossy" | "stale" | "missing" | "unknown"
    }
  } | {
    kind: "web"
    state: {
      days?: integer
      dimension?: "page" | "entry" | "exit" | "referrer" | "utm_source" | "utm_medium" | "utm_campaign" | "utm_term" | … 8 more
      segment?: object
      include?: "attribution"[]
    }
  }
}

Response 200

{
  id: string
  orgId: string
  projectId: string | null
  ownerPrincipalId: string
  name: string
  slug: string | null
  filter: {
    state: {
      query: string
      environment: string
      release: string
      assignee: string
      status: "NEW" | "ONGOING" | "RESOLVED" | "ARCHIVED" | "REGRESSED"[]
      level: "fatal" | "error" | "warning" | "info" | "debug"[]
      sort: "lastSeen" | "firstSeen" | "eventCount" | "userCount" | "priority" | "actionability" | "revenueAtRisk" | "accountsAffected"
      order: "asc" | "desc"
      hours: integer | null
      priority: "HIGH" | "MEDIUM" | "LOW"[]
    }
    columns: Record<string, boolean>
  }
  surface: "issues" | "explore" | "logs" | "replays" | "infra" | "metrics" | "web"
  query: {
    kind: "explore"
    query: {
      dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
      fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
      field?: string
      groupBy?: string
      filters: object[]
      sameTrace?: object
      limit?: integer
      intervalMinutes?: integer
      hours?: integer
    }
  } | {
    kind: "logs"
    state: {
      q: string
      severity: "trace" | "debug" | "info" | "warn" | "error" | "fatal"[]
      environment: string
      traceId: string
      hours: integer
      pinned: string[]
    }
  } | {
    kind: "replays"
    state: {
      query: string
      sort: "newest" | "oldest" | "errors" | "rage_clicks" | "duration" | "notable"
      hideViewed: boolean
    }
  } | {
    kind: "infra"
    state: {
      kind?: "host" | "machine" | "container" | "pod" | "workload" | "function" | "paas_service" | "datastore"
      provider?: string
      environment?: string
      service?: string
      signal?: "metrics" | "logs" | "events" | "traces"
      state?: "live" | "lossy" | "stale" | "missing" | "unknown"
    }
  } | {
    kind: "web"
    state: {
      days: integer
      dimension?: "page" | "entry" | "exit" | "referrer" | "utm_source" | "utm_medium" | "utm_campaign" | "utm_term" | … 8 more
      segment?: object
      include?: "attribution"[]
    }
  } | null
  visibility: "PRIVATE" | "ORG"
  pinned: boolean
  editable: boolean
  starred: boolean
  createdAt: string
  updatedAt: string
}

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

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

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

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

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

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

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

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

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

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

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

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

Request

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

DELETE/orgs/{orgSlug}/views/{viewId}/star

Requires bearerAuth

Parameters

Parameters for DELETE /orgs/{orgSlug}/views/{viewId}/star
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
viewIdrequiredpathstringmin length 1, max length 64

Response 200

{
  viewId: string
  starred: 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 DELETE https://api.bucker.io/orgs/{orgSlug}/views/{viewId}/star \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/views/{viewId}/star

Requires bearerAuth

Parameters

Parameters for PUT /orgs/{orgSlug}/views/{viewId}/star
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
viewIdrequiredpathstringmin length 1, max length 64

Response 200

{
  viewId: string
  starred: 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 PUT https://api.bucker.io/orgs/{orgSlug}/views/{viewId}/star \
  -H "authorization: Bearer $BUCKER_TOKEN"