Role, Skill and Allowlist Endpoints
Endpoints for roles, skills and the skill and tool allowlists.
Roles & skills
| Method | Path | Description |
|---|---|---|
GET |
/v1/roles |
local — list session-prompt roles stored as .md files under prompts/ (name, size, updated_at), returned under roles and, for older clients, the same list again under rules |
GET |
/v1/role/*name |
local — read one role |
POST PATCH DELETE |
/v1/role |
local — create / update (with optional rename) / delete a role |
GET |
/v1/skills |
local — list installed skills |
GET |
/v1/skill/*name |
local — read one installed skill: name, description, path, source, content, deletable, plus files — every UTF-8 file under the skill's scripts/ references/ assets/ directories as {path, content}, sorted by path, dotfiles skipped and anything over 256 KiB omitted (v1.0.2) |
DELETE |
/v1/skill |
local — remove one installed skill |
Rules were renamed to roles in v1.1.0. The /v1/rules, /v1/rule/*name and /v1/rule routes remain as aliases of the role handlers, so older clients keep working.
Operator notes were removed in v1.0.23: /v1/notes, /v1/note/*name and /v1/note (formerly /v1/knowledge*) no longer exist. Put standing instructions in a role or a skill instead.
Allowlists
| Method | Path | Description |
|---|---|---|
GET POST |
/v1/allowlist |
local — both allowlists in one object, skill and tool. GET reads ?scope=global|project (with ?work_dir= required for project) for the skill block and ?prefix= to narrow the tool block. POST takes {skill: {name, scope?, work_dir?}} to toggle one skill and/or {tool: {prefix, entries}} to replace just that prefix's auto-approve entries (the same call the TUI's /mcp → permission makes), so unrelated rules survive; every entry must start with prefix, and prefix* collapses the rest. A block left out is untouched |