REST API
Use the REST API as the direct HTTP interface for creating, reading, and updating workspace work from services, scripts, and CI.
Authentication
Use API Keys for trusted backend services, scripts, CI jobs, and other workspace-scoped automation.
Use OAuth Apps when an app needs user-approved access or needs actions tied to the signed-in member.
What the API covers
The REST API covers workspace data such as initiatives, bugs, tasks, comments, documents, files, members, teams, taxonomy, and connected workflow records. Use the API reference for operation names, request fields, response fields, and schemas.
Choose auth based on the job:
| Auth type | Use it for |
|---|---|
| Workspace API key | Backend services, internal scripts, CI, sync jobs, and trusted workspace automation. |
| OAuth access token | Apps, MCP clients, and agent integrations that need user-approved workspace access and the signed-in member's identity. |
Agent work uses OAuth user tokens and follows the lifecycle described in Agent Sessions. Use Build a Local Agent or Build a Cloud Agent for implementation flow, then use the API reference for exact calls.
Documents and files
Use the document operations when automation needs to list documents by title, type, status, linked task, creator, or updater, or fetch one document body.
For images and videos, request a signed upload URL, upload the file, then use the authenticated asset URL in task descriptions, comments, or documents. Operation names, request fields, and response fields are listed in the API reference under Files.
Limits and errors
REST API responses with bodies are JSON. Successful operations return 200, 201, or 204.
Failed requests return an error object with code and message. Use the API reference for endpoint-specific response codes and schemas.
If you receive 429, pause and retry after the delay in the message. Public API requests are limited per credential; the default is 200 requests per 15 minutes with a burst cap of 40 per minute. Avoid tight polling loops. Cache stable data and use Webhooks when a service needs to react to changes.