Skip to Content
Skilder

List roles in the key’s workspace

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

Published state only, ordered by creation time. Paginate with limit and the nextCursor value from the previous page. Any workspace role may list; a key needs read:roles.

Authorization

apiKey
headerAuthorizationBearer <token>

Workspace API key (SKA_...).

Query Parameters

limit?integer

Page size, 1 to 100

Range1 <= value <= 100
Default20
cursor?string

The nextCursor of the previous page; omit for the first page. Opaque: pass it back unchanged

Length1 <= length

Response Body

One page of roles

application/json
  1. response
data*array<>

The items on this page

pagination*

Where this page sits in the collection

Example Request
curl -X GET 'https://app.skilder.ai/api/v1/roles'
Example Response
{  "data": [    {      "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"      }    }  ],  "pagination": {    "limit": 20,    "nextCursor": "bzE6MjA"  }}