Create a role
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
application/json- body
name*stringRole name
1 <= lengthdescription?stringShort description
instructions?stringRole instructions (markdown)
color*RoleColorDisplay color of the role
"BLUE""GRAY""GREEN""ORANGE""PINK""PURPLE""RED""YELLOW"teamId?stringLeaf team (org unit) to attach the role to; defaults to the workspace default team
1 <= lengthskillIds?array<>Ids of the skills the role starts with
slug?stringSlug, unique in the workspace. Creating with a slug that already exists returns that role, or 409 (see the operation)
1 <= lengthAn existing role with the same slug (idempotent create)
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 POST 'https://app.skilder.ai/api/v1/roles' \ -H 'Content-Type: application/json' \ -d '{ "name": "Support agent", "color": "BLUE"}'{ "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" }}List roles in the key’s workspace GET
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`.
Read one role GET
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.

