Skip to Content
Skilder

Create a role

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

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.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Request Body

application/json
  1. body
name*string

Role name

Length1 <= length
description?string

Short description

instructions?string

Role instructions (markdown)

color*RoleColor

Display color of the role

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

Leaf team (org unit) to attach the role to; defaults to the workspace default team

Length1 <= length
skillIds?array<>

Ids of the skills the role starts with

slug?string

Slug, unique in the workspace. Creating with a slug that already exists returns that role, or 409 (see the operation)

Length1 <= length

Response Body

An existing role with the same slug (idempotent create)

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' \  -H 'Content-Type: application/json' \  -d '{  "name": "Support agent",  "color": "BLUE"}'
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"  }}