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.
Pull requests
List, create, and update GitHub pull requests, GitLab merge requests, and Bitbucket pull requests through /api/v1/workspaces/{workspaceId}/pull-requests. Calls use the authenticated member's stored provider token, so repository access matches the connected OAuth grant for each provider.
Creation requires headBranch and baseBranch. The head branch must already exist on the remote — agents and CI jobs typically push it before opening the request. Updates identify a pull request or merge request by provider, repoId, and identifier because numbers are not globally unique across repositories.
Bitbucket pull requests support reviewers by account UUID. Bitbucket does not support labels or assignees, and declined pull requests cannot be reopened through the API.
Open the Pull Requests routes in the API reference for request and response schemas.
Documents and files
Document operations list documents by title, type, status, linked task, creator, or updater, and fetch one document body. Use PUT to replace editable fields on an existing document. Use PATCH with ordered text operations such as replace_text, insert_before, insert_after, or delete_text to update part of the document body without replacing the full content.
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.