Read one role
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
roleId*stringRole id
1 <= lengthstate?stringWhich 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
"published""published""draft"The requested representation
application/json- response
A role, as its published state or as its open draft (see state).
id*stringRole id
slug*|Workspace-unique slug, when one was given at creation
name*stringRole name
description*|Short description
instructions*|Role instructions (markdown)
color*RoleColorDisplay color of the role
"BLUE""GRAY""GREEN""ORANGE""PINK""PURPLE""RED""YELLOW"teamId*|Id of the team (leaf org unit) the role belongs to
skillIds*array<string>Ids of the skills this role includes
disabled*booleanOperational flag; a disabled role is left out of the catalog agents see
ownerId*|Owner user id; on a draft, the pending owner when the draft transfers ownership
createdAt*|Creation time (ISO 8601)
updatedAt*|Last change to the role (ISO 8601), opening a draft included; publishedAt is the last publish
publishedAt*|Last publish time (ISO 8601). Creation publishes the first version, so it is null only while a creation has not finished
state*stringWhich representation this is: the published state, or the open draft
"published""draft"draft*|The open draft, on both representations; null when no draft is open
curl -X GET 'https://app.skilder.ai/api/v1/roles/0x3c4d'{ "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" }}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.
Update a role (into its draft) PATCH
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.

