Skip to Content
Skilder

Publish a role’s draft

In beta. This endpoint can still change in ways that break your integration. See the REST API overview.
POST
/roles/{roleId}/publish

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.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Path Parameters

roleId*string

Role id

Length1 <= length

Request Body

application/json
  1. body
label?string

Version label recorded on the published snapshot

Length1 <= length <= 200

Response Body

The role’s new published state

application/json
  1. response

A role, as its published state or as its open draft (see state).

id*string

Role id

slug*|

Workspace-unique slug, when one was given at creation

name*string

Role name

description*|

Short description

instructions*|

Role instructions (markdown)

color*RoleColor

Display color of the role

Value in"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*boolean

Operational 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*string

Which representation this is: the published state, or the open draft

Value in"published""draft"
draft*|

The open draft, on both representations; null when no draft is open

Example Request
curl -X POST 'https://app.skilder.ai/api/v1/roles/0x3c4d/publish' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "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"  }}