REST API

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

Use the versioned base path for all new integrations:

/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:

/api/v1/{hash}/...

You can find the hash in Project settings.

API tokens

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

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

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:

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 for the authentication error body.

For example:

HTTP

GET /api/v1/{hash}/board
Authorization: Bearer YOUR_API_KEY
Accept: application/json

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.

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

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

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 permission for the target project.
Create, update, move, reorder, or delete resources	Edit projects permission for the target project.
List workspace projects	View projects returns all workspace projects. Without it, the response contains only projects in which the token owner participates as an external member.
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

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.

Create a board:

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:

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 for updating, moving, and deleting boards.

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.

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

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 an upload can 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. If you cannot establish the result, resolve it before resubmitting.

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

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

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

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

{
  "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

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

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

{
  "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:

{
  "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:

{
  "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"
}

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.
409	The project state conflicts with the requested command.
429	Request rate limit exceeded.
500	Unexpected export or server error.

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.
• 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.

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

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

Resource	Description
Projects	List, create, import, rename, and delete workspace projects.
Exports	Export projects as JSON or for Unity, Unreal Engine, and Godot.
Boards	Manage boards and folders, and retrieve their contents.
Elements	Manage elements, their attachments, linked boards, and the project's starting element.
Connections	Create and edit connections between board items.
Notes	Create and edit notes on boards.
Comments	Read project comment threads and replies.
Jumpers	Manage jumpers that point to project elements.
Branches and conditions	Manage branches and their if, else-if, and else conditions.
Variables	Manage global project variables and their values.
Assets	Upload and download files, and organize assets into folders.
Components	Manage reusable components, folders, and covers.
Attributes	Manage attributes on elements, boards, and components.
CSS	Retrieve and update the project's custom styles.