# Boards

Source: https://docs.arcweave.com/rest-api/boards
Section: REST API
Description: REST API endpoints for listing and managing boards and board folders

Board endpoints let you retrieve the project board tree and a board's items, inspect a board, and create or modify boards and board folders.

## Endpoints

Context: Arcweave docs > REST API > Boards > Endpoints

### Get boards

Context: Arcweave docs > REST API > Boards > Endpoints > Get boards

`GET /api/v1/{hash}/board`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board
```

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

**Response**

Returns `200 OK`.

The response includes the root board so clients can reconstruct the complete board and folder hierarchy. The root is an internal folder container with `parentId: null`; it is not a playable board and cannot be moved or deleted.

```json
[
  {
    "id": "b0",
    "name": "Root",
    "type": "folder",
    "parentId": null,
    "children": ["folder_1"],
    "elementCount": 0,
    "noteCount": 0,
    "connectionCount": 0,
    "branchCount": 0,
    "jumperCount": 0
  },
  {
    "id": "b1",
    "name": "Main Board",
    "type": "board",
    "parentId": "folder_1",
    "children": [],
    "elementCount": 5,
    "noteCount": 3,
    "connectionCount": 10,
    "branchCount": 3,
    "jumperCount": 1
  },
  {
    "id": "folder_1",
    "name": "Chapter One",
    "type": "folder",
    "parentId": "b0",
    "children": ["b1"],
    "elementCount": 0,
    "noteCount": 0,
    "connectionCount": 0,
    "branchCount": 0,
    "jumperCount": 0
  }
]
```

Entries are sorted by ID, not by their position in the board tree. Use each folder's `children` array for the order of its boards and folders.

**Summary fields**

| Field             | Description                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `id`              | Board or folder ID.                                                                                                    |
| `name`            | Board or folder name.                                                                                                  |
| `type`            | `board` for a regular board or `folder` for the root and board folders. Use this field to determine the resource type. |
| `parentId`        | ID of the direct parent folder. The root returns `null`.                                                               |
| `children`        | IDs of the folder's direct child boards and folders. Regular boards cannot have children and return an empty array.    |
| `elementCount`    | Number of elements directly contained by a regular board.                                                              |
| `noteCount`       | Number of notes directly contained by a regular board.                                                                 |
| `connectionCount` | Number of connections directly contained by a regular board.                                                           |
| `branchCount`     | Number of branches directly contained by a regular board.                                                              |
| `jumperCount`     | Number of jumpers directly contained by a regular board.                                                               |

The response uses the same fields for every entry to provide a stable schema. Folder entries—including the root—cannot directly contain project items, so their item counts are `0`. Regular boards cannot contain child boards or folders, so their `children` value is `[]`.

### Get board elements

Context: Arcweave docs > REST API > Boards > Endpoints > Get board elements

`GET /api/v1/{hash}/board/{boardID}/elements`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board/{boardID}/elements
```

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

**Response**

Returns `200 OK`.

```json
[
  {
    "id": "e2",
    "title": "String title",
    "x": 10205,
    "y": 10769,
    "width": 138,
    "height": 100,
    "theme": "red",
    "hasContent": true,
    "componentCount": 0,
    "attributeCount": 2,
    "outputCount": 4
  }
]
```

`title` contains the element title in the project's main language, or the first available translation when the main language has no title. `hasContent` is `true` when the element has content in any language.

### Get board notes

Context: Arcweave docs > REST API > Boards > Endpoints > Get board notes

`GET /api/v1/{hash}/board/{boardID}/notes`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board/{boardID}/notes
```

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

**Response**

Returns `200 OK` with compact note objects in board order:

```json
[
  {
    "id": "n1",
    "content": "Testing note",
    "x": 3100,
    "y": 2200,
    "width": 50,
    "height": 100,
    "theme": "cyan",
    "autoHeight": true
  }
]
```

### Get board jumpers

Context: Arcweave docs > REST API > Boards > Endpoints > Get board jumpers

`GET /api/v1/{hash}/board/{boardID}/jumpers`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board/{boardID}/jumpers
```

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

**Response**

Returns `200 OK` with compact jumper objects in board order:

```json
[
  {
    "id": "jump1",
    "x": 900,
    "y": 15000,
    "width": 185,
    "height": 86,
    "elementId": "e1"
  }
]
```

### Get board branches

Context: Arcweave docs > REST API > Boards > Endpoints > Get board branches

`GET /api/v1/{hash}/board/{boardID}/branches`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board/{boardID}/branches
```

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

**Response**

Returns `200 OK` with compact branch objects in board order. Condition values are IDs, not expanded condition objects.

```json
[
  {
    "id": "br2",
    "x": 500,
    "y": 500,
    "theme": "default",
    "conditions": {
      "ifCondition": "cond3",
      "elseIfConditions": ["cond4", "cond5", "cond6"],
      "elseCondition": "cond7"
    }
  }
]
```

### Get board connections

Context: Arcweave docs > REST API > Boards > Endpoints > Get board connections

`GET /api/v1/{hash}/board/{boardID}/connections`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board/{boardID}/connections
```

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

**Response**

Returns `200 OK` with compact connection objects in board order:

```json
[
  {
    "id": "con2",
    "sourceid": "e2",
    "sourceType": "elements",
    "targetid": "e1",
    "targetType": "elements",
    "sourceFace": "right",
    "targetFace": "left",
    "label": "<p>Continue</p>",
    "labelLocation": 0.5,
    "labelWidth": 100,
    "theme": "default",
    "type": "Bezier"
  }
]
```

`label` contains the label HTML in the project's main language, or the first available translation when the main language has no label. Use [Get connection](https://docs.arcweave.com/rest-api/connections#get-connection) to retrieve every translation.

The five board-item collection endpoints return `404 Not Found` when the board does not exist and `400 Bad Request` when `{boardID}` identifies a folder, because folders cannot contain board items.

### Get board

Context: Arcweave docs > REST API > Boards > Endpoints > Get board

`GET /api/v1/{hash}/board/{boardID}`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/board/{boardID}
```

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

**Response**

Returns `200 OK` with the stored board object:

```json
{
  "id": "b1",
  "name": "Board 1",
  "customId": "custom_b1",
  "elements": ["e1", "e2"],
  "notes": ["n1"],
  "jumpers": ["jump1"],
  "branches": ["br1"],
  "connections": ["con1", "con2"],
  "comments": ["comment1"],
  "attributes": ["board_attribute_9"]
}
```

Regular boards include their item and attribute ID collections. Folder boards contain `children` instead of board-item collections. Use the [attribute endpoints](https://docs.arcweave.com/rest-api/attributes#get-board-attributes) to read and modify board attributes.

The `comments` collection contains thread IDs. Use [List project comments](https://docs.arcweave.com/rest-api/comments#list-project-comments) to retrieve thread content and replies, and match each thread's `position.id` to the board ID.

### Create board or folder

Context: Arcweave docs > REST API > Boards > Endpoints > Create board or folder

`POST /api/v1/{hash}/board`

**Request**

```http title="HTTP"
POST /api/v1/{hash}/board
```

```bash title="curl"
curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/board"
```

Create a regular board:

```json
{
  "name": "API Board",
  "customId": "apiBoard",
  "parentId": "folder_1",
  "index": 0
}
```

Create a folder:

```json
{
  "type": "folder",
  "name": "API Folder"
}
```

| Property   | Required | Type                          | Description                                                                                                      |
| ---------- | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `type`     | No       | String                        | `board` or `folder`. Defaults to `board`.                                                                        |
| `name`     | No       | String                        | Defaults to `Untitled board` for boards or `New Folder` for folders.                                             |
| `customId` | No       | String                        | Arcscript ID for a regular board. A unique ID is generated from the name when omitted. Not accepted for folders. |
| `parentId` | No       | String or `null`              | Parent folder ID. Defaults to the root board container.                                                          |
| `index`    | No       | Non-negative integer or `"-"` | Position in the parent folder. Defaults to `"-"`, which appends the item.                                        |

The parent, when supplied, must exist and must be a folder.

A board `customId` must match `^[A-Za-z$][0-9A-Za-z_]*$`: start with a letter or `$`, followed by letters, numbers, or underscores. It cannot be an Arcscript reserved identifier such as `if`, `true`, or `random`, or duplicate any existing board or component custom ID in the project.

**Response**

Returns `201 Created` with the generated resource ID and project version data:

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

### Update board

Context: Arcweave docs > REST API > Boards > Endpoints > Update board

`PATCH /api/v1/{hash}/board/{boardID}`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/board/{boardID}
```

```bash title="curl"
curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}"
```

```json
{
  "name": "Updated Board Name"
}
```

Request fields:

| Property   | Required | Type   | Description                                             |
| ---------- | -------- | ------ | ------------------------------------------------------- |
| `name`     | No       | String | Updated board or folder name.                           |
| `customId` | No       | String | Set a regular board custom ID only when one is missing. |

Supply at least one of `name` or `customId`. The custom ID must satisfy the [creation rules](https://docs.arcweave.com/rest-api/boards#create-board-or-folder). You may set a missing ID or resend the current one, but changing an existing non-empty custom ID is not supported. Folders do not accept `customId`.

**Response**

Returns `200 OK` with project version data:

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

### Move or reorder board

Context: Arcweave docs > REST API > Boards > Endpoints > Move or reorder board

`PATCH /api/v1/{hash}/board/{boardID}/index`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/board/{boardID}/index
```

```bash title="curl"
curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/board/{boardID}/index"
```

```json
{
  "parentId": "folder_1",
  "index": 0
}
```

Request fields:

| Property   | Required | Type                 | Description                                                              |
| ---------- | -------- | -------------------- | ------------------------------------------------------------------------ |
| `parentId` | No       | String or `null`     | Target folder. Omit to keep the current parent; use `null` for the root. |
| `index`    | Yes      | Non-negative integer | New position within the target folder.                                   |

- `index` is required. An index past the end of the target folder places the item last.
- Omit `parentId` to reorder within the current folder.
- Use `"parentId": null` to move the item to the root.
- The target parent must be a folder.
- The root board cannot be moved.
- A folder cannot be moved into itself or one of its descendants.

**Response**

Returns `200 OK` with project version data:

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

### Delete board

Context: Arcweave docs > REST API > Boards > Endpoints > Delete board

`DELETE /api/v1/{hash}/board/{boardID}`

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/board/{boardID}
```

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

Deleting a board deletes its contents. Deleting a folder deletes its entire subtree, including the boards and their contents.

If the deleted board or folder subtree contains the project's starting element, Arcweave automatically clears the starting element to `null`. You do not need to clear it before deleting the board, and no replacement starting element is selected automatically. Use [Set the starting element](https://docs.arcweave.com/rest-api/elements#set-the-starting-element) to select an element on a remaining board.

At least one playable board must remain. Deleting the last playable board, or a folder containing all remaining playable boards, returns `409 Conflict` without applying the deletion. This error has `type: "integrity_conflict"` and `conflictType: "invalid_target"`. A playable board is a regular board (`type: "board"`), even if it is empty; folders and the internal root do not count. Create another board before retrying the deletion if necessary.

The internal root cannot be deleted; attempting to delete it returns `400 Bad Request`.

**Response**

Returns `200 OK` with project version data:

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

## Common errors

Context: Arcweave docs > REST API > Boards > Common errors

| Status | Meaning                                                                                             |
| ------ | --------------------------------------------------------------------------------------------------- |
| `400`  | Invalid payload, folder used as an item board, root mutation, non-folder parent, or recursive move. |
| `403`  | Project permission denied.                                                                          |
| `404`  | Project, board, or requested parent not found.                                                      |
| `409`  | Deletion would leave no playable boards, or the board tree changed before the command was applied.  |