Arcweave Documentation

Appearance

Boards ​

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 ​

Get boards # GET/api/v1/{hash}/board

Request

http
GET /api/v1/{hash}/board
bash
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": "folder_1",
    "name": "Chapter One",
    "type": "folder",
    "parentId": "b0",
    "children": ["b1"],
    "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
  }
]

Summary fields

FieldDescription
idBoard or folder ID.
nameBoard or folder name.
typeboard for a regular board or folder for the root and board folders. Use this field to determine the resource type.
parentIdID of the direct parent folder. The root returns null.
childrenIDs of the folder's direct child boards and folders. Regular boards cannot have children and return an empty array.
elementCountNumber of elements directly contained by a regular board.
noteCountNumber of notes directly contained by a regular board.
connectionCountNumber of connections directly contained by a regular board.
branchCountNumber of branches directly contained by a regular board.
jumperCountNumber 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 # GET/api/v1/{hash}/board/{boardID}/elements

Request

http
GET /api/v1/{hash}/board/{boardID}/elements
bash
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
  }
]

Get board notes # GET/api/v1/{hash}/board/{boardID}/notes

Request

http
GET /api/v1/{hash}/board/{boardID}/notes
bash
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 # GET/api/v1/{hash}/board/{boardID}/jumpers

Request

http
GET /api/v1/{hash}/board/{boardID}/jumpers
bash
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 # GET/api/v1/{hash}/board/{boardID}/branches

Request

http
GET /api/v1/{hash}/board/{boardID}/branches
bash
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 # GET/api/v1/{hash}/board/{boardID}/connections

Request

http
GET /api/v1/{hash}/board/{boardID}/connections
bash
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"
  }
]

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 # GET/api/v1/{hash}/board/{boardID}

Request

http
GET /api/v1/{hash}/board/{boardID}
bash
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 to read and modify board attributes.

The comments collection contains thread IDs. Use List project comments to retrieve thread content and replies, and match each thread's position.id to the board ID.

Create board or folder # POST/api/v1/{hash}/board

Request

http
POST /api/v1/{hash}/board
bash
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"
}
PropertyRequiredTypeDescription
typeNoStringboard or folder. Defaults to board.
nameNoStringDefaults to Untitled board for boards or New Folder for folders.
customIdNoStringArcscript ID for a regular board. A unique ID is generated from the name when omitted. Not accepted for folders.
parentIdNoString or nullParent folder ID. Defaults to the root board container.
indexNoNon-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 # PATCH/api/v1/{hash}/board/{boardID}

Request

http
PATCH /api/v1/{hash}/board/{boardID}
bash
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:

PropertyRequiredTypeDescription
nameNoStringUpdated board or folder name.
customIdNoStringSet 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. 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 # PATCH/api/v1/{hash}/board/{boardID}/index

Request

http
PATCH /api/v1/{hash}/board/{boardID}/index
bash
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:

PropertyRequiredTypeDescription
parentIdNoString or nullTarget folder. Omit to keep the current parent; use null for the root.
indexYesNon-negative integerNew position within the target folder.
  • index is required.
  • 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 # DELETE/api/v1/{hash}/board/{boardID}

Request

http
DELETE /api/v1/{hash}/board/{boardID}
bash
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 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 ​

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