API overview
Base URL, authentication, and response conventions for the REST API.
The REST API is the same surface the web UI and the MCP server both use. Nothing writes anywhere else.
Base URL and auth
The base URL is /api/v1. Every request authenticates with a workspace scoped API key, printed once by pnpm seed.
Authorization: Bearer vt_...Resources
| Resource | Endpoints |
|---|---|
| Teams | GET/POST /teams |
| Issues | GET/POST /issues, GET/PATCH /issues/:identifier |
| Comments | GET/POST /issues/:identifier/comments |
| Projects | GET/POST /projects, PATCH /projects/:id |
| Initiatives | GET/POST /initiatives, PATCH /initiatives/:id |
| Cycles | GET/POST /cycles |
| Labels | GET/POST /labels |
| Users | GET /users |
| Documents | GET/POST /documents, GET/PATCH/DELETE /documents/:id |
| Updates | GET/POST /updates, GET /updates/candidates |
| Relations | GET/POST /issues/:identifier/relations, DELETE /issues/:identifier/relations/:relationId |
Conventions
The API is built to be agent friendly, so most references are by human readable key rather than internal id:
- Teams by key, for example
VOID. - Issues by identifier, for example
VOID-12. - Workflow states by name, for example
In Progress. - Users by email, or
mefor the API key's owner. - Cycles by number, or
current. - Projects and initiatives by name.
- Unknown labels are created on the fly rather than rejected.
Example
curl -s localhost:3000/api/v1/issues \
-H "Authorization: Bearer $VOIDTRACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"team": "VOID", "title": "Ship the MCP server", "priority": 2, "labels": ["mcp"]}'Full reference
Every endpoint, generated straight from the route handlers, is documented in the API Reference section: request and response schemas, parameters, and auth requirements per resource.
Prefer talking to VoidTrack from an agent instead of curl? See MCP.