Skip to Content
Skilder

Update a role (into its draft)

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

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.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Path Parameters

roleId*string

Role id

Length1 <= length

Request Body

application/json
  1. body
name?string

New role name

Length1 <= length
description?string

New short description

instructions?string

New role instructions (markdown), replacing the current ones

color?RoleColor

Display color of the role

Value in"BLUE""GRAY""GREEN""ORANGE""PINK""PURPLE""RED""YELLOW"
teamId?string

Move the role to this leaf team (org unit) of the workspace

Length1 <= length
skillIds?array<>

Full replacement skill membership (set semantics)

ownerId?string

Transfer ownership (owner-scoped; the transfer publishes with the draft)

Length1 <= length
disabled?boolean

Operational flag, applied to the published state directly

Response Body

The role as the caller now sees it (draft representation while their draft is open)

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 PATCH 'https://app.skilder.ai/api/v1/roles/0x3c4d' \  -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"  }}