REST API
Read and write the project record from your own code, under the same permissions a person has.
The REST API gives pipelines, scripts and other systems the same record the app shows, under the same permissions. A personal access token carries the abilities it was minted with and the team or project it is scoped to; every endpoint declares the ability it needs; every write accepts an idempotency key and every change emits a webhook event.
Every response wraps its payload in data, every list in data with meta and links, and every failure in one error envelope with a stable code. Ids are strings, timestamps ISO 8601.
What is live today
| Resource | Routes |
|---|---|
| Ping | GET /v1/ping |
| Me | GET /v1/me |
| Notifications | GET /v1/me/notifications, POST /v1/me/notifications/{notification}/read, POST /v1/me/notifications/read-all |
| Alert destinations | GET /v1/me/alert-destinations, PUT /v1/me/alert-destinations |
| Teams | GET /v1/teams, GET /v1/teams/current, GET /v1/teams/{team}, POST /v1/teams, PATCH /v1/teams/{team}, DELETE /v1/teams/{team} |
| Team members and invitations | GET /v1/teams/{team}/members, GET …/members/{member}, POST …/members, PATCH …/members/{member}/role, DELETE …/members/{member}, GET …/invitations, DELETE …/invitations/{invitation} |
| Roles | GET /v1/roles, GET /v1/roles/{role}, POST /v1/roles, PATCH /v1/roles/{role}, DELETE /v1/roles/{role} |
| Groups | GET /v1/groups, GET /v1/groups/{group}, POST /v1/groups, PATCH /v1/groups/{group}, PUT /v1/groups/{group}/members, DELETE /v1/groups/{group} |
| Tokens | GET /v1/tokens, GET /v1/tokens/{token}, POST /v1/tokens, DELETE /v1/tokens/{token} |
| Webhook endpoints | GET /v1/webhook-endpoints, GET …/{endpoint}, POST /v1/webhook-endpoints, POST …/{endpoint}/pause, …/resume, …/rotate-secret, …/test, DELETE …/{endpoint} |
| Webhook deliveries and events | GET /v1/webhook-deliveries, GET …/{delivery}, POST …/{delivery}/retry, POST /v1/webhook-deliveries/retry-dead, GET /v1/webhook-events |
| Activity | GET /v1/activity?subject_type=…&subject_id=… |
| Projects | GET /v1/projects, GET /v1/projects/{project}, POST /v1/projects, PATCH /v1/projects/{project}, POST /v1/projects/{project}/archive, POST /v1/projects/{project}/restore, DELETE /v1/projects/{project} |
| Clients | GET /v1/clients, GET /v1/clients/{client}, POST /v1/clients, PATCH /v1/clients/{client}, POST /v1/clients/{client}/archive, POST /v1/clients/{client}/restore, DELETE /v1/clients/{client} |
| Components | GET /v1/projects/{project}/components, POST /v1/projects/{project}/components, GET /v1/components/{component}, PATCH …/{component}, POST …/{component}/archive, POST …/{component}/restore, DELETE …/{component} |
| Environments | GET /v1/projects/{project}/environments, POST /v1/projects/{project}/environments, GET /v1/environments/{environment}, PATCH …/{environment}, POST …/{environment}/freeze, …/unfreeze, …/health, DELETE …/{environment} |
| Stakeholders | GET /v1/projects/{project}/stakeholders, POST /v1/projects/{project}/stakeholders, GET /v1/stakeholders/{stakeholder}, PATCH …/{stakeholder}, DELETE …/{stakeholder} |
| Personas | GET /v1/projects/{project}/personas, POST /v1/projects/{project}/personas, GET /v1/personas/{persona}, PATCH …/{persona}, POST …/{persona}/archive, POST …/{persona}/restore, DELETE …/{persona} |
| Epics | GET /v1/projects/{project}/epics, POST /v1/projects/{project}/epics, GET /v1/epics/{epic}, PATCH …/{epic}, POST …/{epic}/status, DELETE …/{epic}, GET …/{epic}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| Work items | GET /v1/projects/{project}/work-items, POST /v1/projects/{project}/work-items, GET /v1/me/work-items, GET /v1/work-items/{item}, PATCH …/{item}, POST …/{item}/status, POST …/{item}/assign, PUT …/{item}/acceptance-criteria, DELETE …/{item}, GET …/{item}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| Requirements | GET /v1/projects/{project}/requirements, POST /v1/projects/{project}/requirements, GET /v1/requirements/{requirement}, PATCH …/{requirement}, POST …/{requirement}/status, DELETE …/{requirement}, GET …/{requirement}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| Business rules | GET /v1/projects/{project}/business-rules, POST /v1/projects/{project}/business-rules, GET /v1/business-rules/{rule}, PATCH …/{rule}, POST …/{rule}/status, DELETE …/{rule}, GET …/{rule}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| Use cases | GET /v1/projects/{project}/use-cases, POST /v1/projects/{project}/use-cases, GET /v1/use-cases/{useCase}, PATCH …/{useCase}, POST …/{useCase}/status, PUT …/{useCase}/steps, DELETE …/{useCase}, GET …/{useCase}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| RAID log | GET /v1/projects/{project}/raid-items, POST /v1/projects/{project}/raid-items, GET /v1/raid-items/{raidItem}, PATCH …/{raidItem}, POST …/{raidItem}/status, DELETE …/{raidItem}, GET …/{raidItem}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| Decisions | GET /v1/projects/{project}/decisions, POST /v1/projects/{project}/decisions, GET /v1/decisions/{decision}, PATCH …/{decision}, POST …/{decision}/status, DELETE …/{decision}, GET …/{decision}/revisions, GET …/revisions/{revision}, POST …/revisions/{revision}/restore |
| Labels | GET /v1/projects/{project}/labels, POST /v1/projects/{project}/labels, PATCH /v1/labels/{label}, DELETE /v1/labels/{label}; pinned through label_ids on the work item endpoints |
| Links | GET /v1/projects/{project}/links?artefact_type=…&artefact_id=…, POST /v1/projects/{project}/links, DELETE /v1/links/{link} |
| Attachments | GET /v1/projects/{project}/attachments?artefact_type=…&artefact_id=…, POST /v1/projects/{project}/attachments (multipart), GET /v1/attachments/{attachment}/download, DELETE /v1/attachments/{attachment} |
| Comments | GET /v1/projects/{project}/comments?artefact_type=…&artefact_id=…, POST /v1/projects/{project}/comments, PATCH /v1/comments/{comment}, POST …/{comment}/resolve, POST …/{comment}/reopen, DELETE …/{comment} |
| Watchers | GET /v1/projects/{project}/watchers?artefact_type=…&artefact_id=…, POST /v1/projects/{project}/watchers, DELETE /v1/watchers/{watcher} |
| Glossary | GET /v1/projects/{project}/glossary, POST /v1/projects/{project}/glossary, GET /v1/glossary/{term}, PATCH …/{term}, POST …/{term}/status, DELETE …/{term} |
| Data entities | GET /v1/projects/{project}/data-entities, POST /v1/projects/{project}/data-entities, GET /v1/data-entities/{entity}, PATCH …/{entity}, POST …/{entity}/status, PUT …/{entity}/fields, DELETE …/{entity} |
| Design references | GET /v1/projects/{project}/design-references, POST /v1/projects/{project}/design-references, GET /v1/design-references/{reference}, PATCH …/{reference}, DELETE …/{reference} |
| Repositories | GET /v1/projects/{project}/repositories, POST /v1/projects/{project}/repositories, GET /v1/repositories/{repository}, PATCH …/{repository}, POST …/{repository}/disconnect, POST …/{repository}/reconnect, DELETE …/{repository} |
| Project settings | GET /v1/projects/{project}/settings, PATCH /v1/projects/{project}/settings |
The API Reference has one page per operation, generated from the API's own OpenAPI document: the fields, the refusals, the events it fires, the MCP tools that wrap it, and a playground that calls the live API. The families above are the ones the ability catalogue marks as live.
Start here
Quickstart
Mint a token, make the first call and receive the first signed webhook.
Authentication
The token format, ability-scoped authorization, revocation and rotation.
Ability catalogue
Every ability string, its family, and what enforces it today.
Errors
The one envelope every failure uses, and every code with its remediation.
How is this guide?
Last updated on