Publish a role’s draft
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.
apiKeyAuthorizationBearer <token>Workspace API key (SKA_...).
roleId*stringRole id
1 <= lengthapplication/json- body
label?stringVersion label recorded on the published snapshot
1 <= length <= 200The role’s new published state
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/0x3c4d/publish' \ -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" }}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`.
Discard a role’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: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).

