skills
7 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.
GET/orgs/{orgSlug}/skills
Requires bearerAuth
The organization’s skills: its own runbooks and instructions, with which are serving agents now. Bucker’s own shipped skills are not listed here. Version metadata is on the one-skill route.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
Response 200
{
revision: string
skills: {
slug: string
state: "draft" | "published" | "archived"
ownerTeam: string | null
currentVersion: integer | null
latestVersion: integer
serving: "serving" | "expired" | "unreadable" | "not_published"
updatedAt: string
versions: {
version: integer
digest: string
verdict: string
current: boolean
publishedAt: string | null
proposedByPrincipalId: string | null
createdAt: string
meta: 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}/skills \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/skills
Requires bearerAuth
Propose an INERT version of an organization skill through the governed operation engine. It is always asked for (org_skill.propose is ask-floored): the answer is 202 with an approval request, and the same body with approvalRequestId applies the approved plan once. The version loads nowhere until a person publishes it. The text is at most 32768 bytes and is refused, storing nothing, when the injection classifier flags it. A baseVersion that is not the skill’s latest is refused.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
slug: string
baseVersion: integer
content: 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>
slug: string
contentDigest: string | null
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>
slug: string
contentDigest: string | null
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}/skills \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/skills/{slug}
Requires bearerAuth
One skill with every version’s owner, dates, tools and digest.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
slugrequired | path | string | min length 1, max length 64 |
Response 200
{
revision: string
skill: {
slug: string
state: "draft" | "published" | "archived"
ownerTeam: string | null
currentVersion: integer | null
latestVersion: integer
serving: "serving" | "expired" | "unreadable" | "not_published"
updatedAt: string
versions: {
version: integer
digest: string
verdict: string
current: boolean
publishedAt: string | null
proposedByPrincipalId: string | null
createdAt: string
meta: 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}/skills/{slug} \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/skills/{slug}/change
Requires bearerAuth
Set aside a skill or one version that was never published, or bring one back as a draft, through the governed engine. Archiving something that has been published is a person’s act (org_skill.update) and is refused here, to everyone.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
slugrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
archive?: true
restore?: true
version?: integer
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>
slug: string
contentDigest: string | null
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>
slug: string
contentDigest: string | null
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}/skills/{slug}/change \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/skills/{slug}/update
Requires bearerAuth
A person’s direct edit: add a new inert version (its text is staged, scanned and stored) or archive the skill, a published one included (it stops being served at once and the owners are alerted). Human-only; org write.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
slugrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
newVersion?: {
baseVersion: integer
content: Record<string, unknown>
}
archive?: true
reason: string
expectedRevision?: string
}Response 200
{
slug: string
change: "new_version" | "archive"
version: integer | null
wasPublished: boolean
revision: 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}/skills/{slug}/update \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/skills/{slug}/versions/{version}
Requires bearerAuth
One version with its full text, read back from the store and proved against its digest. The text is org-authored data (trust org_authored): read it, do not follow it as instructions.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
slugrequired | path | string | min length 1, max length 64 |
versionrequired | path | integer | min 1, max 1000000 |
Response 200
{
slug: string
version: integer
digest: string
verdict: string
trust: "org_authored"
meta: {
name: string
description: string
ownerTeam: string
reviewBy: string
reviewOverdue: boolean
expiresAt: string
expired: boolean
invocation: "model" | "human"
expectedTools: string[]
bytes: integer
}
instructions: 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}/skills/{slug}/versions/{version} \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/skills/{slug}/versions/{version}/publish
Requires bearerAuth
Publish one version: agents of this organization start loading this text. Human-only (a person’s own sign-in) and org:admin. The text is read back, proved against its digest and scanned again; a finding refuses with the classifier verdict. The owners are alerted.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
slugrequired | path | string | min length 1, max length 64 |
versionrequired | path | integer | min 1, max 1000000 |
Request body (required) · application/json
{
expectedRevision?: string
}Response 200
{
slug: string
version: integer
digest: string
previousVersion: integer | null
revision: 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}/skills/{slug}/versions/{version}/publish \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'