# 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 |