List roles in the key’s workspace
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
limit?integerPage size, 1 to 100
1 <= value <= 10020cursor?stringThe nextCursor of the previous page; omit for the first page. Opaque: pass it back unchanged
1 <= lengthOne page of roles
application/json- response
data*array<>The items on this page
pagination*Where this page sits in the collection
curl -X GET 'https://app.skilder.ai/api/v1/roles'{ "data": [ { "id": "0x3c4d", "slug": "support-agent", "name": "Support agent", "description": "Answers customer tickets with the support playbook.", "instructions": "Always link the help-center article you used.", "color": "BLUE", "teamId": "0x7a8b", "skillIds": [ "0x1a2b", "0x1a2c" ], "disabled": false, "ownerId": "0x5e6f", "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-11-02T09:30:00.000Z", "publishedAt": "2026-11-02T09:30:00.000Z", "state": "published", "draft": { "authorId": "0x5e6f", "authorName": "Ada Lovelace", "openedAt": "2026-11-02T09:30:00.000Z" } } ], "pagination": { "limit": 20, "nextCursor": "bzE6MjA" }}Discard a skill’s open draft DELETE
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).
Create a role POST
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.

