Skip to Content
Skilder

Read one role

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

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.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Path Parameters

roleId*string

Role id

Length1 <= length

Query Parameters

state?string

Which representation to read. draft returns the open draft when you hold it, or when you are an admin or the owner and the key may publish the resource

Default"published"
Value in"published""draft"

Response Body

The requested representation

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