Role, Skill and Allowlist Endpoints
Last updated
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. POST and PATCH take {name, content}; a name already taken returns 409. DELETE takes ?name= (or {name}); 404 when the role does not exist |
GET | /v1/skills | local — list installed skills as {name, description?}, TUI-only skills excluded; since v1.2.0 skills from sources disabled through /v1/config/skill_source are not scanned and do not appear |
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 1 MiB omitted (v1.0.2) |
DELETE | /v1/skill | local — ?name=. Moves one installed skill to ~/.config/agenvoy/skills/.Trash and returns {ok, trashed}. Only skills under ~/.config/agenvoy/skills/ can be removed — not .system or .system_design, and not other sources (403) |
Rules were renamed to roles in v1.1.0. Five routes remain as aliases of the role handlers —
GET /v1/rules, GET /v1/rule/*name, and POST / PATCH / DELETE /v1/rule — 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 |