Roles
GET /v1/roles
Section titled “GET /v1/roles”The app’s agent roles (name, description, version)
- Scope:
agents:read
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
roles |
object[] |
Errors are problem documents with a code.
GET /v1/roles/{name}
Section titled “GET /v1/roles/{name}”A role: its parsed fields and the Markdown file
- Scope:
agents:read
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
name |
path | string | yes | Role name: 1..64 of a-z 0-9 - (not starting or ending with -) |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | ||
description |
string | ||
version |
integer | ||
tags |
string[] | ||
tools |
string[] | ||
model |
string,null | ||
skills |
string[] | ||
mcp |
string[] | ||
apis |
string[] | ||
metadata |
object | ||
instructions |
string | ||
markdown |
string | ||
updated_at |
integer |
Errors are problem documents with a code.
PUT /v1/roles/{name}
Section titled “PUT /v1/roles/{name}”Create or replace a role from its Markdown file (a — header with name and description, then the instructions; the format of Claude Code’s agents/*.md)
- Scope:
agents:write
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
name |
path | string | yes | Role name: 1..64 of a-z 0-9 - (not starting or ending with -) |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
markdown |
string | yes |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | ||
version |
integer |
Errors are problem documents with a code.
DELETE /v1/roles/{name}
Section titled “DELETE /v1/roles/{name}”Delete a role no agent has (409 role.in_use otherwise)
- Scope:
agents:write
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
name |
path | string | yes | Role name: 1..64 of a-z 0-9 - (not starting or ending with -) |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
deleted |
string |
Errors are problem documents with a code.