Skills, tasks and projects API
Skills and playbooks CRUD, running a skill, GitHub skill import, learning-lane skill proposals, and the durable task board.
Skills are the reusable procedure substrate; tasks and projects are the durable work items agents create and humans track. All routes are org-session scoped; proposal accept/dismiss additionally require an org admin. See Skills and playbooks.
Skills
A content change (name, description, or sections) bumps current_version and
appends an immutable revision; runs pinned to an older version are never mutated.
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/skills |
List skills for the org, newest first. | Query kind (filter; an unknown kind matches nothing), view (picker returns a slim list, library omits sections), limit (picker only, 1-2000). Returns {skills}. |
| GET | /api/skills/:id |
Fetch one skill with full sections. | 404 skill not found. |
| POST | /api/skills |
Create a skill and its version-1 revision. | Body: name (required), kind (default skill), description, tags[], sections ({overview[], procedure[], verify[]}). 201. 409 on a name collision. |
| PATCH | /api/skills/:id |
Partial update; a content change bumps the version. | Body (any subset): name, description, tags[], sections. A tags-only edit does not mint a version. 404 skill not found. |
| DELETE | /api/skills/:id |
Delete a skill (revisions cascade). | {deleted: true, id}. Historical runs keep their recorded version for provenance. |
| POST | /api/skills/:id/run |
Run a skill: create a real run pinned to its current version. | Header Idempotency-Key. Body: prompt (required), engine, model. 201 {id} new / 200 {id} replay. 400 model_not_allowed, 403 model_provider_not_ready, 404 skill not found, 409 idempotency_key_reused, 503 when admission is closed. |
Skill import
Devin-style import of SKILL.md files from the org’s GitHub repos. The GitHub
credential stays server-side. A bad ref or unconfigured backend is 400; a GitHub
upstream failure is 502; a repo not available to the org is 403.
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/skills/import/scan |
List the SKILL.md files a repo offers, each tagged already-imported. |
Query repo (required, "owner/name"). |
| POST | /api/skills/import |
Import selected paths at repo HEAD into org skills. | Body: repo (required), paths[] (required, non-empty). Returns a per-path outcome (unchanged is a no-op). |
Skill proposals
Learning-lane skill-revision proposals. Listing is org-visible; accept and dismiss are org-admin.
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/skills/proposals |
List proposals, newest first. | Query status (proposed/accepted/dismissed). Returns {proposals} (each carries the exact proposed_content a future accept would materialize). |
| POST | /api/skills/proposals/:id/accept |
Accept: mint a real skill revision (or a new playbook). | Org-admin. {proposal, skill_id, version}. 404 proposal not found, 409 proposal already resolved. |
| POST | /api/skills/proposals/:id/dismiss |
Dismiss a proposal (recorded, never deleted). | Org-admin. {proposal}. 404/409 as above. |
Tasks
Durable, org-scoped tasks grouped per project and rendered as a Kanban board.
Status is one of todo, in_progress, done, archived. See Task
composer.
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/tasks |
List org tasks, scoped by project or all. | Query project (key), project_id (uuid), scope=all (cross-project), limit (default 100). Returns {tasks}. |
| POST | /api/tasks |
Create a task. | Body: title (required), status (default todo), project_id, project_key, body, priority. 201. 404 project not found. |
| PATCH | /api/tasks/:id |
Partial update. | Body (any subset): title, body, status, priority, order. 404 task not found. |
| DELETE | /api/tasks/:id |
Delete a task. | {deleted: true, id}. 404 task not found. |
Projects
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/projects |
List org projects. | Query scope=all (include archived), limit (default 100). Returns {projects}. |
| POST | /api/projects |
Create or ensure a project by key. | Body: key (required), display_name, repo_full_name. 201. |
| PATCH | /api/projects/:id |
Update a project. | Body: display_name (non-empty if provided), archived (boolean), sort_order. 404 project not found. |