> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarca.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Build integrations with Arca using the REST API.

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)**

```http theme={null}
Authorization: Bearer arca_your_key_here
```

**`X-API-Key` header**

```http theme={null}
X-API-Key: arca_your_key_here
```

All API keys start with the `arca_` prefix. Create and manage keys in the Arca app under **Settings → API Keys**.

<Warning>
  API keys are secrets. Never embed them in client-side code or public
  repositories.
</Warning>

If the key is missing, invalid, or expired, the API returns `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:

```
2026-03-18T18:34:49.000Z
```

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. To **remove** a date, pass `null` or an empty string (`""`).

## Errors

All error responses return JSON with a single `error` field:

```json theme={null}
{ "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                                                                      |