REST API
The REST API is the direct HTTP path for apps, services, scripts, and CI jobs that need to read or update workspace data.
Authentication
API Keys fit trusted backend services, scripts, CI jobs, and other workspace-scoped automation.
OAuth Apps fit apps that need user-approved access or actions tied to the signed-in member.
What the API covers
Want to read or update workspace data from your own software? The REST API is the direct HTTP path.
When the job is clear, the API reference gives you the exact route.
Choose auth based on the job:
| Auth type | Best 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. Start with Build a Local Agent or Build a Cloud Agent before choosing individual REST calls.
Documents and files
Document operations list documents by title, type, status, linked task, creator, or updater, and 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. When you are ready to build this, open the Files routes in the API reference.
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.
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.