The Software Development plugin's API
All under /api/v1/x/dev/, 404 while the plugin is off.
| Scope | For |
|---|---|
dev:read | Reading. |
dev:write | Tasks and sprints. |
dev:admin | A project's settings, access, columns and fields. |
[!IMPORTANT] On top of the scope, your role in the project decides (owner, member, viewer; desk admins act as owners): a project you have no access to is 404, an action your role doesn't allow is 403. A token limited to a unit only reaches projects connected to a unit at or below it.
| Endpoint | What |
|---|---|
GET orgs | Organizations you can create a project in. |
GET projects?orgId=&archived=true | Your projects, starred first: key, role, owners, people, open tasks. |
POST projects | Create (dev:admin): orgId, name, key, template (kanban, bugs, scrum, empty), description, unitIds, unitRole. You are its owner. |
GET projects/<id> | Columns (with wipLimit), fields, open sprints, epics, people (who can be assigned) and everyone (who can be mentioned). |
PATCH projects/<id> | name, description, sprints (owners). |
POST projects/<id>/archive, …/restore; GET projects/<id>/export | Archive (read-only), restore, everything as JSON (owners). |
PUT, DELETE projects/<id>/star | Star or unstar for yourself. |
GET projects/<id>/board?assignee=&type=&label=&epicId=&field=<fieldId>:<value>&q=&sprint=all&limit=&more= | Columns with cards; with sprints on, the running sprint unless sprint=all. Each column has its first limit cards (default 50; a done column the latest done first), matching (how many match the filters) and total. more=<columnId>:<n>,… loads more of some. |
GET projects/<id>/backlog? (the board's filters, limit, more) | Open tasks not in a sprint, and each planned or running sprint with its tasks: the first limit of each (default 50), with backlogTotal and backlogEstimate, and total and estimate per sprint. more=backlog:<n>,<sprintId>:<n> loads more. |
GET projects/<id>/access | units (connected, with role and how many people) and entries: each person with role, ownRole, sources ({ type: 'unit', unitId, unitName } or { type: 'manual' }). |
POST projects/<id>/access/units, PATCH …/units/<unitId>, DELETE …/units/<unitId> | Connect a unit with a role, change its role, disconnect it (owners). |
POST projects/<id>/access/people, PATCH …/people/<userId>, DELETE …/people/<userId> | Add someone by name with a role; set their own role (null: what their units give); remove the manual access (owners). A change that would leave no active owner is 409 last_owner. |
GET projects/<id>/units, GET projects/<id>/candidates?q= | The pickers for units of the organization and active staff (owners). |
POST projects/<id>/columns, PATCH …/columns/<id>, POST …/columns/<id>/move, DELETE …/columns/<id>?moveTo= | Columns (owners): add (name, done, wipLimit, index), change, move to an index, delete (its tasks go to moveTo). |
POST projects/<id>/fields, PATCH …/fields/<id>, DELETE …/fields/<id> | Fields of the project's own (owners): name, kind (text, number, select, multi_select, date, person), options. |
GET projects/<id>/sprints?all=true, POST …/sprints, PATCH …/sprints/<id>, POST …/start, POST …/complete, DELETE …/sprints/<id> | Sprints (members): plan (name, goal, startDate, endDate), start one at a time, complete (moveTo: a planned sprint for the unfinished tasks, or the backlog), delete a planned one. |
GET count | Your open tasks, in total and per project. |
GET report?days=&projectId=&orgId=&tz= | Created and done per day, per project and per type, the median cycle time in hours; with projectId also open tasks per column with their limits. |
POST tasks | Create (members): projectId, title, optional description, type (also epic), priority, assigneeId (an owner or member), labels, estimate, dueDate, parentId (a subtask; it joins its task's sprint), epicId, sprintId, fields ({ fieldId: value }), columnId, caseRef (links it). |
GET tasks/<id>, PATCH tasks/<id>, DELETE tasks/<id> | A task with subtasks, an epic's tasks, cases, watchers, comments and history; change it (fields sets the values given, null clears one); delete it (owners and its creator). |
POST tasks/<id>/move | { columnId, afterId }: after that card (null: at the top; left out: at the bottom). Entering a done column tells the linked cases and the watchers. |
POST tasks/<id>/comments | { body, mentions } (Markdown; mentions: user ids with access, who get an email and start watching). Viewers too. |
PUT, DELETE tasks/<id>/watch | Watch or stop watching. |
POST tasks/<id>/links, DELETE tasks/<id>/links/<ref> | Link or unlink a case of the project's organization that you can see. |
GET cases/<ref>/tasks | The tasks linked to a case, in projects you can use. |
MCP tools
| Scope | Tools |
|---|---|
dev:read | list_dev_projects, get_dev_project, get_dev_project_access, list_dev_tasks, get_dev_task, dev_report |
dev:write | create_dev_task, update_dev_task (fields by name, column, sprint, epic, parent, links, comments with mentions, watching), manage_dev_sprint |
dev:admin | create_dev_project, update_dev_project (also archives), change_dev_project_access, change_dev_columns, change_dev_fields |
Webhook events
| Event | With |
|---|---|
dev.project.created, dev.project.archived, dev.project.restored, dev.project.access_changed | |
dev.sprint.started, dev.sprint.completed | |
dev.task.created | |
dev.task.updated | The changed fields. |
dev.task.moved | from, to. |
dev.task.done | |
dev.task.commented | Who, and who was mentioned; not the text. |
dev.task.linked | case. |
dev.task.deleted |
Audited: creating, changing, archiving and restoring a project, every access and role change, fields, columns, and deleting a task.
Access hooks: the plugin provides the kind project (who can use a project and why; what a person can use) and reports
every grant, revocation and role change, including those that follow from the desk: a person moved out of a unit
(units_changed) or a unit deleted (unit_deleted), which the desk now tells plugins through ctx.onStaff.