# REST API

Source: https://docs.arcweave.com/rest-api/overview
Section: REST API
Description: Authenticate with Arcweave's REST API for read and write access to your projects

Arcweave's REST API provides read and write access to projects in a Team workspace. You can retrieve exports, create and edit project content, import projects, synchronize assets and components, or build custom integrations.

> ⚠️ The REST API is available to Team workspaces only. Access depends on both the API key's project permissions and the permissions of the member who created it.

## Base path and version

Context: Arcweave docs > REST API > Base path and version

Use the versioned base path for all new integrations:

```text
/api/v1
```

The unversioned `/api` routes currently remain as aliases, but integrations should use `/api/v1` so their contract is explicit.

Most project endpoints include the project's hash:

```text
/api/v1/{hash}/...
```

You can find the hash in [Project settings](https://docs.arcweave.com/project-tools/settings#project-hash).

## API tokens

Context: Arcweave docs > REST API > API tokens

Arcweave displays API tokens as **API keys** in the workspace interface.

### Create an API key

Context: Arcweave docs > REST API > API tokens > Create an API key

1. Open the workspace **API** section.
2. Click **Create new key** and enter a descriptive name.
3. Under **Project permissions**, select **Read projects**, **Write projects**, or both. **Read projects** is selected by default; at least one permission is required.
4. Click **Create**, then copy the key from the **Key** column and store it securely.

See [Workspace API](https://docs.arcweave.com/workspaces/api) for key management instructions.

> ⚠️ API keys grant access to workspace project data. Never expose a key in browser code, a public repository, or an application distributed to end users.

## Authentication and headers

Context: Arcweave docs > REST API > Authentication and headers

Send the API key as a bearer token and include `Accept: application/json` on every request, including `GET` requests. Requests with a JSON body should also send `Content-Type: application/json`:

```http
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json
```

The `Accept` header ensures that missing or invalid credentials return a JSON `401 Unauthorized` response. Without it, an unauthenticated request can return `302 Found` with a redirect to `/login`; clients that follow the redirect receive an HTML login page. See [Error responses](https://docs.arcweave.com/rest-api/overview#error-responses) for the authentication error body.

For example:

```http title="HTTP"
GET /api/v1/{hash}/board
Authorization: Bearer YOUR_API_KEY
Accept: application/json
```

```bash title="curl"
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/board"
```

File uploads use `multipart/form-data` instead of `application/json`. [Creating a media asset](https://docs.arcweave.com/rest-api/assets#create-asset-or-folder) uploads the file and registers the asset in one request. Let your HTTP client set the multipart header and boundary.

In curl tabs for JSON mutations, `--data @payload.json` refers to the JSON request body shown below the tabs. Save that body as `payload.json`, or replace the argument with equivalent inline JSON.

## Permissions

Context: Arcweave docs > REST API > Permissions

### API key permissions

Context: Arcweave docs > REST API > Permissions > API key permissions

Each API key has one or both of these permissions:

| Workspace label    | Token permission | Allowed requests                                                                              |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------- |
| **Read projects**  | `project:read`   | `GET` and `HEAD`: list, view, and export projects and their content.                          |
| **Write projects** | `project:write`  | `POST`, `PATCH`, and `DELETE`: create, import, update, and delete projects and their content. |

The permissions are independent. A key with **Write projects** alone cannot read or export data. Select both for an integration that needs read and write access. A request without its required token permission returns `403 Forbidden`.

New keys created in the workspace interface start with **Read projects** selected. Keys that existed before project permissions were introduced were assigned both **Read projects** and **Write projects**. Review their permissions in the workspace's API section and use **Edit key** to change them. Permission changes apply immediately.

### Workspace and project permissions

Context: Arcweave docs > REST API > Permissions > Workspace and project permissions

A key acts as the member who created it, within the key's workspace. Token permissions do not grant that member additional workspace or project access. The following access requirements also apply:

| Operations                                            | Access requirement                                                                                                                                               |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve project resources, CSS, and asset files      | **View projects list** permission for the target project.                                                                                                        |
| Create, update, move, reorder, or delete resources    | **Edit projects** permission for the target project.                                                                                                             |
| List workspace projects                               | **View projects list** permission for the workspace. Without it, this endpoint returns `403 Forbidden`, even if the key owner has access to individual projects. |
| Create a project                                      | **Create projects** permission for the workspace, plus available project capacity.                                                                               |
| Import a project                                      | **Import projects** permission for the workspace, plus available project and item capacity.                                                                      |
| Rename a project                                      | **Edit projects** permission for the target project.                                                                                                             |
| Delete a project                                      | **Delete projects** permission for the target project.                                                                                                           |
| Retrieve JSON, Unity, Unreal Engine, or Godot exports | The corresponding export feature must be enabled for the workspace, and the project must belong to the token's workspace.                                        |

## Make your first write

Context: Arcweave docs > REST API > Make your first write

Create a key with both **Read projects** and **Write projects**, then choose a project you can edit in that key's workspace. Replace `YOUR_API_KEY` and `PROJECT_HASH` below with your key and [project hash](https://docs.arcweave.com/project-tools/settings#project-hash).

Create a board:

```bash
curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"name":"API example"}' \
  "https://arcweave.com/api/v1/PROJECT_HASH/board"
```

The response is `201 Created` and includes the new board's `id`. Replace `BOARD_ID` with that value to read the board back:

```bash
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/board/BOARD_ID"
```

The response is `200 OK` with the board data. See [Boards](https://docs.arcweave.com/rest-api/boards) for updating, moving, and deleting boards.

## Rate limits

Context: Arcweave docs > REST API > Rate limits

API quotas are shared by all users and API keys in the workspace associated with the key. Each workspace has independent quotas. Versioned `/api/v1` routes and their unversioned `/api` aliases share the same quotas. Requests through the [Arcweave MCP server](https://docs.arcweave.com/integrations/mcp) also count toward these workspace quotas.

| Quota                                 | Requests per minute  |
| ------------------------------------- | -------------------- |
| All REST API requests                 | 60 × workspace seats |
| Project imports and exports, combined | 3 × workspace seats  |

Seats are purchased subscription seats, including unused seats and the combined monthly and yearly subscription quantities. A trial workspace with no purchased seats receives a one-seat allowance. Existing plan and API key permissions still apply.

For example, a workspace with five seats can make **300 API requests per minute, including up to 15 project imports and exports combined**. Import and export requests consume both quotas. Exhausting the import/export quota still allows other API requests while the overall quota has capacity.

The import/export quota applies to these endpoints and their unversioned aliases:

- `POST /api/v1/workspace/projects/import`
- `GET` and `HEAD /api/v1/{hash}/json`
- `GET` and `HEAD /api/v1/{hash}/godot`
- `GET` and `HEAD /api/v1/{hash}/unity`
- `GET` and `HEAD /api/v1/{hash}/unreal`

Each quota uses a 60-second window beginning with its first counted request. Requests admitted by the limiter count even if subsequent validation or authorization fails. Requests rejected by the limiter do not consume allowance.

Responses passing through the limiter include `X-RateLimit-Limit` and `X-RateLimit-Remaining`, which report the request allowance and remaining requests. When both quotas apply, these headers describe the quota with fewer remaining requests.

An exhausted quota returns `429 Too Many Requests` with `Retry-After` as an integer number of seconds and `X-RateLimit-Reset` as a Unix timestamp. If multiple applicable quotas are exhausted, these headers describe the longest wait.

### Retrying requests

Context: Arcweave docs > REST API > Rate limits > Retrying requests

A request rejected by the API rate limiter with `429` has not been applied. Wait at least the number of seconds in `Retry-After` before retrying, and coordinate requests across all users, API keys, and workers using the same workspace. Concurrent requests can consume renewed capacity.

A timeout, lost connection, or `5xx` response does not tell you whether a write succeeded. The API does not support the `Idempotency-Key` header: repeating a create or import request can create a second resource or project, and repeating a media upload can create another asset and store another file. Do not automatically retry these requests after an ambiguous failure. First inspect the current project state to determine whether the operation completed; for uploads, check [Get assets](https://docs.arcweave.com/rest-api/assets#get-assets). If you cannot establish the result, resolve it before resubmitting.

A media upload rejected with `410 Gone` expired before file storage began and can be retried with a fresh upload request.

Read requests can be retried after transient failures. Before retrying an update, move, or delete, read the affected resources and check whether the intended change already happened or whether another editor changed the state. These readback checks require **Read projects** permission.

## Response conventions

Context: Arcweave docs > REST API > Response conventions

Create operations normally return `201 Created` with the generated resource ID:

```json
{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"],
  "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c"
}
```

Successful update, move, and delete operations normally return `200 OK`:

```json
{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}
```

`version` is the project version before the request, `newVersion` is the version after the request is successfully applied, and `versionTime` is the update timestamp returned by the project service.

If an operation makes no change, `newVersion` can equal `version` and `versionTime` can be `null`.

### Concurrent edits

Context: Arcweave docs > REST API > Response conventions > Concurrent edits

The returned version fields describe a completed operation. The API does not accept an expected project version or support `If-Match` conditional writes, so these fields do not prevent an update from overwriting another editor's changes.

Send only the fields you intend to change. When a write depends on existing data, read that data first and coordinate writes from your integration. Reading before writing still leaves a window for another editor to make a change. Separate requests are not a single transaction; if a later request fails, earlier successful requests remain applied.

On `409 Conflict`, inspect the error and read the affected resources again. Correct the request for the current project state before retrying. A `409` reports a detected state or relationship conflict; it does not mean every concurrent edit is detected.

### Error responses

Context: Arcweave docs > REST API > Response conventions > Error responses

With `Accept: application/json`, a missing or invalid API key returns `401 Unauthorized` with an `application/json` body:

```json
{
  "error": "Unauthenticated."
}
```

Use the HTTP response status to identify the failure; this authentication error body contains only the `error` field.

Validation and permission errors use a JSON object with a human-readable `title`, HTTP `status`, and optional field errors. These responses have the `application/problem+json` content type:

```json
{
  "title": "Bad Request - element.create payload",
  "status": 400,
  "detail": null,
  "errors": {
    "x": "The x field is required."
  },
  "errorCode": 0
}
```

Concurrent or relationship conflicts return `409 Conflict` and may include `type`, `conflictType`, and `context`:

```json
{
  "title": "Integrity error: Cannot create element on missing board: b1",
  "status": 409,
  "detail": "The target board does not exist.",
  "errors": [],
  "errorCode": 0,
  "type": "integrity_conflict",
  "conflictType": "missing_parent",
  "context": {
    "boardId": "b1",
    "parentType": "board"
  }
}
```

The following table lists the HTTP status codes the API may return:

| Status | Meaning                                                                       |
| ------ | ----------------------------------------------------------------------------- |
| `200`  | Request completed successfully.                                               |
| `201`  | Resource created successfully.                                                |
| `400`  | Invalid payload or unsupported operation.                                     |
| `401`  | Missing or invalid API key.                                                   |
| `403`  | API feature, token permission, workspace access, or member permission denied. |
| `404`  | Project or resource not found.                                                |
| `405`  | HTTP method not supported for the requested path, including POST to the removed `/asset/upload` route. |
| `409`  | The project state conflicts with the requested command.                       |
| `410`  | Media upload reservation expired before file storage began. Retry the upload. |
| `429`  | Request rate limit exceeded.                                                  |
| `500`  | Unexpected export or server error.                                            |

## General request rules

Context: Arcweave docs > REST API > General request rules

- Resource IDs created through the API are server-generated UUIDs. Do not send an `id` when creating a resource unless an endpoint explicitly documents it as a reference.
- Unexpected JSON properties are rejected instead of ignored.
- `PATCH` requests must contain at least one supported field.
- Reorder endpoints end in `/index` and use a zero-based, non-negative `index` request field.
- In create, move, and reorder requests, an `index` at or past the end of the target list appends the item.
- Elements, notes, jumpers, and branches must fit entirely inside the `40000` by `40000` board canvas. Their `x` and `y` coordinates must be non-negative and cannot exceed the canvas dimensions minus the item's width and height.
- Root containers cannot be moved or deleted.
- Moving a folder into itself or one of its descendants is rejected.
- Arcscript sent in a request is parsed before it is saved: code blocks in element content and connection labels, and branch condition scripts. Scripts must be valid and reference existing variables, attributes, and mentioned elements. Invalid scripts return `400 Bad Request` with the title `Bad Request - invalid Arcscript` and an `errors` entry for each affected field. Requests without script fields don't revalidate existing scripts.
- If the project changes while submitted Arcscript is being validated, the request returns `409 Conflict` with `conflictType: "arcscript_context_changed"` and isn't applied. Read the current state and retry.

For element titles/content, connection labels, and component names, see [Localized content](https://docs.arcweave.com/rest-api/localization) for language setup, default-language writes, partial translation updates, and locale errors. Rich-text fields also follow the [field-specific formatting rules](https://docs.arcweave.com/rest-api/rich-text#supported-html).

### Color themes

Context: Arcweave docs > REST API > General request rules > Color themes

The `theme` field on elements, notes, branches, and connections accepts only these case-sensitive values:

`default`, `orange`, `brown`, `gold`, `moss`, `green`, `cyan`, `lightBlue`, `blue`, `purple`, `pink`, `red`.

Creation defaults to `default`. On update, omitting `theme` keeps the current value. Custom color strings and other names are rejected with `400 Bad Request`.

## API reference

Context: Arcweave docs > REST API > API reference

Choose a resource to find its endpoints, request examples, and response formats:

| Resource | Description |
| --- | --- |
| [Projects](https://docs.arcweave.com/rest-api/projects#list-workspace-projects) | List, create, import, rename, and delete workspace projects. |
| [Exports](https://docs.arcweave.com/rest-api/exports) | Export projects as [JSON](https://docs.arcweave.com/rest-api/exports#json-export) or for [Unity](https://docs.arcweave.com/rest-api/exports#export-for-unity), [Unreal Engine](https://docs.arcweave.com/rest-api/exports#export-for-unreal-engine), and [Godot](https://docs.arcweave.com/rest-api/exports#export-for-godot). |
| [Boards](https://docs.arcweave.com/rest-api/boards) | Manage boards and folders, and retrieve their contents. |
| [Elements](https://docs.arcweave.com/rest-api/elements) | Manage elements, their attachments, and the project's starting element. |
| [Connections](https://docs.arcweave.com/rest-api/connections) | Create and edit connections between board items. |
| [Notes](https://docs.arcweave.com/rest-api/notes) | Create and edit notes on boards. |
| [Comments](https://docs.arcweave.com/rest-api/comments) | Read project comment threads and replies. |
| [Jumpers](https://docs.arcweave.com/rest-api/jumpers) | Manage jumpers that point to project elements. |
| [Branches and conditions](https://docs.arcweave.com/rest-api/branches) | Manage branches and their if, else-if, and else conditions. |
| [Variables](https://docs.arcweave.com/rest-api/variables) | Manage global project variables and their values. |
| [Assets](https://docs.arcweave.com/rest-api/assets) | Upload and download files, and organize assets into folders. |
| [Components](https://docs.arcweave.com/rest-api/components) | Manage reusable components, folders, and covers. |
| [Attributes](https://docs.arcweave.com/rest-api/attributes) | Manage attributes on elements, boards, and components. |
| [CSS](https://docs.arcweave.com/rest-api/css) | Retrieve and update the project's custom styles. |