The Arca REST API lets you read and write workspace data (tasks, lists, folders, statuses, labels, members, and comments) from any external application or script.
Base URL
All endpoints are available under:
https://api.getarca.app/api/v1
Authentication
Every request must include a valid API key. You can pass it one of two ways:
Authorization header (recommended)
Authorization: Bearer arca_your_key_here
X-API-Key header
X-API-Key: arca_your_key_here
arca_ prefix. Create and manage keys in the Arca app under Settings → API Keys.
API keys are secrets. Never embed them in client-side code or public
repositories.
401 Unauthorized.
Scopes
Each API key is granted a specific set of scopes. A request is rejected with 403 Forbidden if the key lacks the required scope for the endpoint.
| Scope | Grants access to |
|---|
users:read | Read your own profile (/me) |
workspaces:read | Read workspaces, members, statuses, and labels |
workspaces:write | Create, update, and delete statuses and labels |
folders:read | Read folders |
folders:write | Create, update, and delete folders |
lists:read | Read lists |
lists:write | Create, update, and delete lists |
tasks:read | Read tasks and subtasks |
tasks:write | Create, update, and delete tasks |
comments:read | Read task comments |
comments:write | Create task comments |
Role restrictions
API operations are additionally constrained by your workspace role:
- Viewers can use read scopes (
tasks:read, folders:read, etc.) but cannot create, edit, or delete any resources.
- Members can create and edit resources but cannot delete folders or lists.
- Admins and owners have full access, including deleting folders and lists.
Additionally, workspace admins and owners can apply access restrictions to individual members, limiting them to specific folders and lists. Restricted members receive filtered results on list endpoints, and 403 Forbidden when accessing, creating, updating, or deleting resources in folders or lists outside their permitted scope.
Timestamps
All timestamps in responses are UTC ISO-8601 strings, for example:
When sending date values in request bodies (due_date, start_date), use ISO 8601 UTC format. A string without a timezone suffix (e.g., 2026-03-18T17:00:00) is treated as UTC.
Errors
All error responses return JSON with a single error field:
{ "error": "A description of the problem" }
| Status | Meaning |
|---|
400 | Bad request, missing or invalid parameter |
401 | Unauthorized, API key is missing, invalid, or expired |
403 | Forbidden, your workspace role prohibits this action, or your key lacks the required scope |
404 | Not found, the resource does not exist or is not accessible to you |
500 | Internal server error |
