Update a role (into its draft)
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
roleId*stringRole id
1 <= lengthapplication/json- body
name?stringNew role name
1 <= lengthdescription?stringNew short description
instructions?stringNew role instructions (markdown), replacing the current ones
color?RoleColorDisplay color of the role
"BLUE""GRAY""GREEN""ORANGE""PINK""PURPLE""RED""YELLOW"teamId?stringMove the role to this leaf team (org unit) of the workspace
1 <= lengthskillIds?array<>Full replacement skill membership (set semantics)
ownerId?stringTransfer ownership (owner-scoped; the transfer publishes with the draft)
1 <= lengthdisabled?booleanOperational flag, applied to the published state directly
The role as the caller now sees it (draft representation while their draft is open)
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 PATCH 'https://app.skilder.ai/api/v1/roles/0x3c4d' \ -H 'Content-Type: application/json' \ -d '{}'{ "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" }}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.
Delete a role DELETE
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`.

