{"openapi":"3.1.0","info":{"title":"Skilder Public API","version":"1.3.1","description":"Public REST API for the Skilder platform. Authenticate with a workspace API key: `Authorization: Bearer SKA_...`."},"servers":[{"url":"../v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"skills","description":"Skills: the instructions and resources an agent runs. Reads return the published state by default; edits land on your draft until it is published."},{"name":"roles","description":"Roles: a named set of skills with its own instructions, attached to a team. Same published and draft lifecycle as skills."},{"name":"export","description":"Download published skills as Agent Skills zip packages, one skill or a bundle. The packages import back into Skilder."},{"name":"meta","description":"The API key you are calling with, and this OpenAPI document."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Workspace API key (SKA_...)."}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details. All /api/v1 errors use this shape.","properties":{"type":{"type":"string","description":"Problem type URI."},"title":{"type":"string","description":"Short summary of the problem type."},"status":{"type":"integer","description":"HTTP status code."},"detail":{"type":"string","description":"Explanation specific to this occurrence."},"instance":{"type":"string","description":"URI of the request that produced the problem."},"code":{"type":"string","description":"Stable machine-readable error code."},"errors":{"type":"array","description":"Per-field details for validation failures.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated path of the field that failed (e.g. name), or the request part (body, query, params) when the failure is not on one field."},"message":{"type":"string","description":"Why the field failed."}}}},"reason":{"type":"string","description":"Why the request was refused. On a 403: INSUFFICIENT_KEY_SCOPE (mint a broader key), INSUFFICIENT_PERMISSIONS (workspace role too low) or WORKSPACE_ACCESS_DENIED (no longer a member of the key's workspace). On a 409: DRAFT_LOCKED (another user holds the open draft) or NO_OPEN_DRAFT (no draft to act on)."},"action":{"type":"string","description":"The ability action that was refused (e.g. update, publish)."},"resource":{"type":"string","description":"The ability resource the refused action targeted (e.g. Skill, Role)."},"draftAuthorId":{"type":["string","null"],"description":"On DRAFT_LOCKED conflicts: id of the user holding the open draft (null when unrecorded)."}},"required":["type","title","status"]},"Skill":{"type":"object","properties":{"id":{"type":"string","description":"Skill id","examples":["0x1a2b"]},"slug":{"description":"Workspace-unique slug, when one was given at creation","examples":["weekly-report"],"type":["string","null"]},"name":{"type":"string","description":"Skill name","examples":["Weekly report"]},"description":{"description":"Short description","examples":["Drafts the weekly status report from the team tracker."],"type":["string","null"]},"instructions":{"description":"Skill instructions (markdown)","examples":["# Weekly report\n\nCollect the closed issues…"],"type":["string","null"]},"disabled":{"type":"boolean","description":"Operational flag; a disabled skill is left out of the catalog agents see","examples":[false]},"ownerId":{"description":"Owner user id; on a draft, the pending owner when the draft transfers ownership","examples":["0x5e6f"],"type":["string","null"]},"createdAt":{"description":"Creation time (ISO 8601)","examples":["2026-10-01T08:00:00.000Z"],"type":["string","null"]},"updatedAt":{"description":"Last change to the skill (ISO 8601), opening a draft included; `publishedAt` is the last publish","examples":["2026-11-02T09:30:00.000Z"],"type":["string","null"]},"publishedAt":{"description":"Last publish time (ISO 8601). Creation publishes the first version, so it is null only while a creation has not finished","examples":["2026-11-02T09:30:00.000Z"],"type":["string","null"]},"state":{"type":"string","enum":["published","draft"],"description":"Which representation this is: the published state, or the open draft","examples":["published"]},"draft":{"anyOf":[{"$ref":"#/components/schemas/DraftMarker"},{"type":"null"}],"description":"The open draft, on both representations; null when no draft is open"}},"required":["id","slug","name","description","instructions","disabled","ownerId","createdAt","updatedAt","publishedAt","state","draft"],"additionalProperties":false,"description":"A skill, as its published state or as its open draft (see `state`)."},"DraftMarker":{"type":"object","properties":{"authorId":{"description":"Id of the user holding the draft lock; null when unrecorded","examples":["0x5e6f"],"type":["string","null"]},"authorName":{"description":"Display name (or email) of the draft author","examples":["Ada Lovelace"],"type":["string","null"]},"openedAt":{"description":"When the draft was opened (ISO 8601)","examples":["2026-11-02T09:30:00.000Z"],"type":["string","null"]}},"required":["authorId","authorName","openedAt"],"additionalProperties":false,"description":"Who holds the open draft, and since when. Carries no draft content."},"Role":{"type":"object","properties":{"id":{"type":"string","description":"Role id","examples":["0x3c4d"]},"slug":{"description":"Workspace-unique slug, when one was given at creation","examples":["support-agent"],"type":["string","null"]},"name":{"type":"string","description":"Role name","examples":["Support agent"]},"description":{"description":"Short description","examples":["Answers customer tickets with the support playbook."],"type":["string","null"]},"instructions":{"description":"Role instructions (markdown)","examples":["Always link the help-center article you used."],"type":["string","null"]},"color":{"$ref":"#/components/schemas/RoleColor"},"teamId":{"description":"Id of the team (leaf org unit) the role belongs to","examples":["0x7a8b"],"type":["string","null"]},"skillIds":{"type":"array","items":{"type":"string"},"description":"Ids of the skills this role includes","examples":[["0x1a2b","0x1a2c"]]},"disabled":{"type":"boolean","description":"Operational flag; a disabled role is left out of the catalog agents see","examples":[false]},"ownerId":{"description":"Owner user id; on a draft, the pending owner when the draft transfers ownership","examples":["0x5e6f"],"type":["string","null"]},"createdAt":{"description":"Creation time (ISO 8601)","examples":["2026-10-01T08:00:00.000Z"],"type":["string","null"]},"updatedAt":{"description":"Last change to the role (ISO 8601), opening a draft included; `publishedAt` is the last publish","examples":["2026-11-02T09:30:00.000Z"],"type":["string","null"]},"publishedAt":{"description":"Last publish time (ISO 8601). Creation publishes the first version, so it is null only while a creation has not finished","examples":["2026-11-02T09:30:00.000Z"],"type":["string","null"]},"state":{"type":"string","enum":["published","draft"],"description":"Which representation this is: the published state, or the open draft","examples":["published"]},"draft":{"anyOf":[{"$ref":"#/components/schemas/DraftMarker"},{"type":"null"}],"description":"The open draft, on both representations; null when no draft is open"}},"required":["id","slug","name","description","instructions","color","teamId","skillIds","disabled","ownerId","createdAt","updatedAt","publishedAt","state","draft"],"additionalProperties":false,"description":"A role, as its published state or as its open draft (see `state`)."},"RoleColor":{"type":"string","enum":["BLUE","GRAY","GREEN","ORANGE","PINK","PURPLE","RED","YELLOW"],"description":"Display color of the role","examples":["BLUE"]}},"examples":{"ValidationFailed":{"summary":"The request failed validation","value":{"type":"about:blank","title":"Bad Request","status":400,"detail":"Request body failed validation.","code":"BAD_USER_INPUT","errors":[{"path":"name","message":"Too small: expected string to have >=1 characters"}],"instance":"/api/v1/skills"}},"InvalidApiKey":{"summary":"No valid API key","value":{"type":"about:blank","title":"Unauthorized","status":401,"detail":"Invalid, expired, or revoked API key.","code":"UNAUTHENTICATED","instance":"/api/v1/skills"}},"InsufficientKeyScope":{"summary":"The key lacks the scope","value":{"type":"about:blank","title":"Forbidden","status":403,"detail":"The API key's scopes do not permit 'publish' on 'Skill'.","code":"FORBIDDEN","reason":"INSUFFICIENT_KEY_SCOPE","action":"publish","resource":"Skill","instance":"/api/v1/skills/0x1a2b/publish"}},"NotFound":{"summary":"No such resource in the key’s workspace","value":{"type":"about:blank","title":"Not Found","status":404,"detail":"Skill not found.","code":"NOT_FOUND","instance":"/api/v1/skills/0x1a2b"}},"DraftLocked":{"summary":"Another user holds the open draft","value":{"type":"about:blank","title":"Conflict","status":409,"detail":"This draft is locked by another user (Ada Lovelace). Take over the draft to edit it.","code":"CONFLICT","reason":"DRAFT_LOCKED","draftAuthorId":"0x5e6f","instance":"/api/v1/skills/0x1a2b"}}}},"paths":{"/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"OpenAPI 3.1 document for this API","description":"This document. Served without authentication: it describes the API and holds no workspace data.","tags":["meta"],"responses":{"200":{"description":"The OpenAPI document"},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}},"security":[]}},"/me":{"get":{"operationId":"getMe","summary":"Identify the authenticated API key","description":"Returns the user and workspace the presented API key is bound to, with the key's public display prefix and granted scopes. Any valid key may call it; it needs no scope.","tags":["meta"],"responses":{"200":{"description":"The authenticated actor","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"Id of the user the API key belongs to","examples":["0x1a2b"]},"workspaceId":{"type":"string","description":"Workspace the API key is bound to","examples":["0x3c4d"]},"key":{"type":"object","properties":{"displayPrefix":{"type":"string","description":"Public display prefix of the key","examples":["SKA_xxxx"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Scope tokens granted to this key; empty if the grant is unusable","examples":[["read:skills","write:skills"]]}},"required":["displayPrefix","scopes"],"additionalProperties":false,"description":"The API key itself, never its secret"}},"required":["userId","workspaceId","key"],"additionalProperties":false}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/skills":{"get":{"operationId":"listSkills","summary":"List skills in the key’s workspace","description":"Published state only, ordered by creation time. Paginate with `limit` and the `nextCursor` value from the previous page. Any workspace role may list; a key needs `read:skills`.","tags":["skills"],"parameters":[{"name":"limit","in":"query","description":"Page size, 1 to 100","required":false,"schema":{"default":20,"examples":[20],"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page; omit for the first page. Opaque: pass it back unchanged","required":false,"schema":{"examples":["bzE6MjA"],"type":"string","minLength":1}}],"responses":{"200":{"description":"One page of skills","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"},"description":"The items on this page"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"description":"Page size actually applied","examples":[20]},"nextCursor":{"description":"Opaque cursor for the next page; null on the last page","examples":["bzE6MjA"],"type":["string","null"]}},"required":["limit","nextCursor"],"additionalProperties":false,"description":"Where this page sits in the collection"}},"required":["data","pagination"],"additionalProperties":false}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}},"post":{"operationId":"createSkill","summary":"Create a skill","description":"Creates a published skill, owned by the caller. Requires the Contributor or Admin role; a key needs `write:skills`. With a `slug`, creation is idempotent: a duplicate returns the existing skill with 200. Its owner's retry finishes a creation that stopped part-way, with 201; 409 while it is still running, or when someone else's retry meets it or a draft is open on it. Parallel creations with one slug create one skill: the others meet it while it is running.","tags":["skills"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Skill name","examples":["Weekly report"]},"description":{"description":"Short description","examples":["Drafts the weekly status report from the team tracker."],"type":"string","maxLength":1024},"instructions":{"description":"Skill instructions (markdown)","type":"string"},"slug":{"description":"Slug, unique in the workspace. Creating with a slug that already exists returns that skill, or 409 (see the operation)","examples":["weekly-report"],"type":"string","minLength":1}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"An existing skill with the same slug (idempotent create)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"201":{"description":"The created skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"409":{"description":"A skill with the same slug has not finished being created, and this request cannot finish it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/skills/{skillId}":{"get":{"operationId":"getSkill","summary":"Read one skill","description":"Any workspace role may read; a key needs `read:skills`. Returns the published state by default. `?state=draft` returns the open draft: 404 when no draft is open, 409 when another user holds it, unless the caller is an admin or the skill’s owner and the key has `publish:skills` (draft content is otherwise visible only to its author), 403 when the caller is a Member, whose role reads published skills only.","tags":["skills"],"parameters":[{"name":"skillId","in":"path","description":"Skill id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x1a2b"]}},{"name":"state","in":"query","description":"Which representation to read. `draft` returns the open draft when you hold it, or when you are an admin or the owner and the key may publish the resource","required":false,"schema":{"default":"published","examples":["published"],"type":"string","enum":["published","draft"]}}],"responses":{"200":{"description":"The requested representation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"403":{"description":"The key lacks `read:skills`, or a Member asked for the draft (their role reads published skills only)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Skill not found, or no draft is open","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The open draft is held by another user","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}},"patch":{"operationId":"updateSkill","summary":"Update a skill (into its draft)","description":"Requires the Contributor or Admin role; a key needs `write:skills`. Content edits land on the caller’s draft, which is opened automatically when none exists; the published state is untouched until an explicit publish. 409 when another user holds the open draft. `disabled` is operational, applied to the published state directly, and owner-scoped (the owner or an admin; a key needs `publish:skills`). `ownerId` transfers ownership (owner-scoped) as part of the draft.","tags":["skills"],"parameters":[{"name":"skillId","in":"path","description":"Skill id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x1a2b"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New skill name","type":"string","minLength":1},"description":{"description":"New short description","type":"string","maxLength":1024},"instructions":{"description":"New skill instructions (markdown), replacing the current ones","type":"string"},"ownerId":{"description":"Transfer ownership (owner-scoped; the transfer publishes with the draft)","type":"string","minLength":1},"disabled":{"description":"Operational flag, applied to the published state directly","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The skill as the caller now sees it (draft representation while their draft is open)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"409":{"description":"The open draft is held by another user","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}},"delete":{"operationId":"deleteSkill","summary":"Delete a skill","description":"Cascade-deletes the skill with its related resources and version history. Irreversible. Owner-scoped: an admin may delete any skill, a contributor only their own; a key needs `write:skills`.","tags":["skills"],"parameters":[{"name":"skillId","in":"path","description":"Skill id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x1a2b"]}}],"responses":{"204":{"description":"Deleted"},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/skills/{skillId}/publish":{"post":{"operationId":"publishSkill","summary":"Publish a skill’s draft","description":"Promotes the skill’s currently open draft to the published state (the version agents run) — nothing else. It takes no edits: make them with `PATCH /skills/{skillId}` first, an ownership transfer included, and the publish carries them. Requires the owner-scoped `publish` ability (a workspace admin or the skill’s owner), which is also what lets the caller promote a draft authored by someone else without taking it over. The body is optional: empty publishes the open draft as-is. Errors: **409 with `reason: NO_OPEN_DRAFT`** when nothing is open to publish (edit it first with PATCH), **403** when the caller is not the skill’s owner or a workspace admin, or the key lacks `publish:skills`.","tags":["skills"],"parameters":[{"name":"skillId","in":"path","description":"Skill id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x1a2b"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"description":"Version label recorded on the published snapshot","examples":["v1.2"],"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"The skill’s new published state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"403":{"description":"Not the owner or an admin, or the key lacks the publish:skills scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Skill not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"No open draft to publish (`reason: NO_OPEN_DRAFT`)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/skills/{skillId}/draft":{"delete":{"operationId":"discardSkillDraft","summary":"Discard a skill’s open draft","description":"Discards the caller’s open draft; the published state is never touched, and the discarded edits cannot be recovered. Requires the Contributor or Admin role; a key needs `write:skills`. This closes the loop PATCH opens: an auto-opened draft that will not be published is released here instead of holding the author lock forever. Errors: **409 with `reason: NO_OPEN_DRAFT`** when nothing is open to discard, **409 with `reason: DRAFT_LOCKED`** when another user holds the draft (a draft is author-private; only its holder may discard it).","tags":["skills"],"parameters":[{"name":"skillId","in":"path","description":"Skill id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x1a2b"]}}],"responses":{"204":{"description":"Draft discarded; the published state is unchanged"},"404":{"description":"Skill not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"No open draft to discard (`reason: NO_OPEN_DRAFT`), or the draft is held by another user (`reason: DRAFT_LOCKED`)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/roles":{"get":{"operationId":"listRoles","summary":"List roles in the key’s workspace","description":"Published state only, ordered by creation time. Paginate with `limit` and the `nextCursor` value from the previous page. Any workspace role may list; a key needs `read:roles`.","tags":["roles"],"parameters":[{"name":"limit","in":"query","description":"Page size, 1 to 100","required":false,"schema":{"default":20,"examples":[20],"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page; omit for the first page. Opaque: pass it back unchanged","required":false,"schema":{"examples":["bzE6MjA"],"type":"string","minLength":1}}],"responses":{"200":{"description":"One page of roles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Role"},"description":"The items on this page"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"description":"Page size actually applied","examples":[20]},"nextCursor":{"description":"Opaque cursor for the next page; null on the last page","examples":["bzE6MjA"],"type":["string","null"]}},"required":["limit","nextCursor"],"additionalProperties":false,"description":"Where this page sits in the collection"}},"required":["data","pagination"],"additionalProperties":false}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}},"post":{"operationId":"createRole","summary":"Create a role","description":"Creates a published role, owned by the caller. Requires the Contributor or Admin role; a key needs `write:roles`. Without a `teamId` the role attaches to the workspace default team. With a `slug`, creation is idempotent: a duplicate returns the existing role with 200. Its owner's retry finishes a creation that stopped part-way, with 201; 409 while it is still running, or when someone else's retry meets it or a draft is open on it. Parallel creations with one slug create one role: the others meet it while it is running.","tags":["roles"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Role name","examples":["Support agent"]},"description":{"description":"Short description","examples":["Answers customer tickets with the support playbook."],"type":"string"},"instructions":{"description":"Role instructions (markdown)","type":"string"},"color":{"$ref":"#/components/schemas/RoleColor"},"teamId":{"description":"Leaf team (org unit) to attach the role to; defaults to the workspace default team","type":"string","minLength":1},"skillIds":{"description":"Ids of the skills the role starts with","examples":[["0x1a2b"]],"type":"array","items":{"type":"string","minLength":1}},"slug":{"description":"Slug, unique in the workspace. Creating with a slug that already exists returns that role, or 409 (see the operation)","examples":["support-agent"],"type":"string","minLength":1}},"required":["name","color"],"additionalProperties":false}}}},"responses":{"200":{"description":"An existing role with the same slug (idempotent create)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}}},"201":{"description":"The created role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}}},"409":{"description":"A role with the same slug has not finished being created, and this request cannot finish it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/roles/{roleId}":{"get":{"operationId":"getRole","summary":"Read one role","description":"Any workspace role may read; a key needs `read:roles`. Returns the published state by default. `?state=draft` returns the open draft: 404 when no draft is open, 409 when another user holds it, unless the caller is an admin or the role’s owner and the key has `publish:roles` (draft content is otherwise visible only to its author), 403 when the caller is a Member, whose role reads published roles only.","tags":["roles"],"parameters":[{"name":"roleId","in":"path","description":"Role id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x3c4d"]}},{"name":"state","in":"query","description":"Which representation to read. `draft` returns the open draft when you hold it, or when you are an admin or the owner and the key may publish the resource","required":false,"schema":{"default":"published","examples":["published"],"type":"string","enum":["published","draft"]}}],"responses":{"200":{"description":"The requested representation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}}},"403":{"description":"The key lacks `read:roles`, or a Member asked for the draft (their role reads published roles only)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Role not found, or no draft is open","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The open draft is held by another user","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}},"patch":{"operationId":"updateRole","summary":"Update a role (into its draft)","description":"Requires the Contributor or Admin role; a key needs `write:roles`. Content edits (including `skillIds` membership, set semantics) land on the caller’s draft, which is opened automatically when none exists; the published state is untouched until an explicit publish. 409 when another user holds the open draft. `disabled` is operational and applied to the published state directly. `ownerId` transfers ownership (owner-scoped) as part of the draft.","tags":["roles"],"parameters":[{"name":"roleId","in":"path","description":"Role id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x3c4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New role name","type":"string","minLength":1},"description":{"description":"New short description","type":"string"},"instructions":{"description":"New role instructions (markdown), replacing the current ones","type":"string"},"color":{"$ref":"#/components/schemas/RoleColor"},"teamId":{"description":"Move the role to this leaf team (org unit) of the workspace","type":"string","minLength":1},"skillIds":{"description":"Full replacement skill membership (set semantics)","type":"array","items":{"type":"string","minLength":1}},"ownerId":{"description":"Transfer ownership (owner-scoped; the transfer publishes with the draft)","type":"string","minLength":1},"disabled":{"description":"Operational flag, applied to the published state directly","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The role as the caller now sees it (draft representation while their draft is open)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}}},"409":{"description":"The open draft is held by another user","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}},"delete":{"operationId":"deleteRole","summary":"Delete a role","description":"Cascade-deletes the role with its version history. Irreversible. Owner-scoped: an admin may delete any role, a contributor only their own; a key needs `write:roles`.","tags":["roles"],"parameters":[{"name":"roleId","in":"path","description":"Role id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x3c4d"]}}],"responses":{"204":{"description":"Deleted"},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/roles/{roleId}/publish":{"post":{"operationId":"publishRole","summary":"Publish a role’s draft","description":"Promotes the role’s currently open draft to the published state (the version agents run) — nothing else. It takes no edits: make them with `PATCH /roles/{roleId}` first, an ownership transfer included, and the publish carries them. Requires the owner-scoped `publish` ability (a workspace admin or the role’s owner), which is also what lets the caller promote a draft authored by someone else without taking it over. The body is optional: empty publishes the open draft as-is. Errors: **409 with `reason: NO_OPEN_DRAFT`** when nothing is open to publish (edit it first with PATCH), **403** when the caller is not the role’s owner or a workspace admin, or the key lacks `publish:roles`.","tags":["roles"],"parameters":[{"name":"roleId","in":"path","description":"Role id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x3c4d"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"description":"Version label recorded on the published snapshot","examples":["v1.2"],"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"The role’s new published state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}}},"403":{"description":"Not the owner or an admin, or the key lacks the publish:roles scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Role not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"No open draft to publish (`reason: NO_OPEN_DRAFT`)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/roles/{roleId}/draft":{"delete":{"operationId":"discardRoleDraft","summary":"Discard a role’s open draft","description":"Discards the caller’s open draft; the published state is never touched, and the discarded edits cannot be recovered. Requires the Contributor or Admin role; a key needs `write:roles`. This closes the loop PATCH opens: an auto-opened draft that will not be published is released here instead of holding the author lock forever. Errors: **409 with `reason: NO_OPEN_DRAFT`** when nothing is open to discard, **409 with `reason: DRAFT_LOCKED`** when another user holds the draft (a draft is author-private; only its holder may discard it).","tags":["roles"],"parameters":[{"name":"roleId","in":"path","description":"Role id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x3c4d"]}}],"responses":{"204":{"description":"Draft discarded; the published state is unchanged"},"404":{"description":"Role not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"No open draft to discard (`reason: NO_OPEN_DRAFT`), or the draft is held by another user (`reason: DRAFT_LOCKED`)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/skills/export":{"get":{"operationId":"exportSkills","summary":"Export several skills as one zip bundle","description":"Streams a zip holding one Agent Skills package folder per skill (published state only). Any workspace role may export; a key needs `read:skills`, and `read:roles` too when filtering by `roleId`. Filter with exactly one of `ids` (comma-separated, max 100) or `roleId` (every skill of that role). All-or-nothing: any id that does not resolve in the key’s workspace fails the whole request with 404. Folder-name collisions inside the bundle get numeric suffixes (`report`, `report-2`, …). A role with no skills yields an empty zip. Downloadable resources with no uploaded file yet are left out of their package. Every App the skills attach is written once under `apps/<name>/`, and no skill folder is named `apps` then; Apps travel only when the key may read them (`read:apps`).","tags":["export"],"parameters":[{"name":"ids","in":"query","description":"Comma-separated skill ids to export (max 100)","required":false,"schema":{"examples":["0x1a2b,0x1a2c"],"type":"string","minLength":1}},{"name":"roleId","in":"query","description":"Export every skill of this role","required":false,"schema":{"examples":["0x3c4d"],"type":"string","minLength":1}}],"responses":{"200":{"description":"Zip bundle of skill packages","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Neither/both filters given, empty `ids`, or more than 100 skills (ids given, or the role’s skills)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A requested skill or the role was not found in the key’s workspace","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Two files of a skill’s package resolve to the same path (SKILL.md, SKILDER.json and mcp.json at its root are taken); rename the resource","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}},"/skills/{skillId}/export":{"get":{"operationId":"exportSkill","summary":"Export one skill as an Agent Skills zip package","description":"Any workspace role may export; a key needs `read:skills`. Streams the skill’s published state as an Agent Skills package: `<skill-name>/SKILL.md`, every related resource at its folder path, declared empty folders, and — when present — the `mcp.json` (suggested servers) and `SKILDER.json` (resource descriptions, suggested tools, App names) sidecars. The skill’s Apps sit beside it under `apps/<name>/` (`app.html`, `SKILDER.json`) when the key may read them (`read:apps`). Downloadable resources with no uploaded file yet are left out.","tags":["export"],"parameters":[{"name":"skillId","in":"path","description":"Skill id","required":true,"schema":{"type":"string","minLength":1,"examples":["0x1a2b"]}}],"responses":{"200":{"description":"The skill package as a zip","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Skill not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Two files of the package resolve to the same path (SKILL.md, SKILDER.json and mcp.json at its root are taken); rename the resource","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"default":{"description":"Error (RFC 9457 problem details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ValidationFailed":{"$ref":"#/components/examples/ValidationFailed"},"InvalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"InsufficientKeyScope":{"$ref":"#/components/examples/InsufficientKeyScope"},"NotFound":{"$ref":"#/components/examples/NotFound"},"DraftLocked":{"$ref":"#/components/examples/DraftLocked"}}}}}}}}}}