Getting started
A two-minute tour of the v1 REST API.
What this API does
The /api/v1/* REST API lets external clients (mobile apps, scripts, server-to-server integrations) read and mutate the same data the web app uses — projects, workspaces, tasks, subtasks, time entries — without going through the browser session.
Authentication is per-organization API keys. Every request operates only on that organization's data.
Quick start
Generate a key
Open Organization Settings → API Keys → Create Key. Copy the secret immediately — it is only displayed once. Keys are prefixed with ba_.
Make a call
curl -H "Authorization: Bearer ba_..." \
https://your-domain/api/v1/workspacesSuccessful list responses are shaped { "data": [ ... ], "total": <n> } (offset paging) or { "data": [ ... ], "pagination": { "nextCursor": <id|null> } } (cursor paging). Single-resource responses are { "data": { ... } }.
Browse the spec
The full OpenAPI 3.1 contract is available at /api/v1/openapi.json. The in-app API Explorer at Settings → API Keys → Open the API Explorer renders it with a live try-it-out panel.
What you can do
Authentication
Send your key, key lifecycle, and security best practices.
Idempotency
Safely retry POST requests with the Idempotency-Key header.
Pagination
Offset and cursor pagination conventions.
Errors
Status codes, error envelope, and validation details.
Resources
| Resource | What it does |
|---|---|
| Projects | Full CRUD over projects and project members. |
| Workspaces | Read workspace boards and stages. |
| Tasks | Create, update, move, and finalize tasks. |
| Subtasks | Manage subtasks nested under a parent task. |
| Time entries | Log and adjust manual time entries. |
| Members, Task types, Tags | Read-only registries. |
Conventions at a glance
- Base URL —
https://your-domain/api/v1. - Auth header —
Authorization: Bearer ba_<key>. - Mutations — JSON bodies with
Content-Type: application/json. - Multi-tenant — Every endpoint filters by the key's organization; cross-org IDs return
404. - Dates — ISO-8601 timestamps in UTC (
YYYY-MM-DDTHH:mm:ss.sssZ).
Not in the API
A few in-app endpoints exist outside /api/v1/ and use the browser session cookie instead of API keys (chat, search, HTML report download). These are intentionally not part of the public API contract.