Arcweave Documentation

Appearance

Elements ​

Element endpoints manage element content and ordering, attached components, attributes, audio, covers, linked boards, outputs, and the project's starting element.

Element endpoints ​

Create element # POST/api/v1/{hash}/element

Request

http
POST /api/v1/{hash}/element
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/element"
json
{
  "boardId": "b1",
  "x": 200,
  "y": 300,
  "width": 320,
  "height": 180,
  "title": "<p>Opening</p>",
  "content": "<p>The story begins.</p>"
}
PropertyRequiredTypeDescription
boardIdYesStringBoard that will contain the element.
xYesNumberHorizontal board coordinate.
yYesNumberVertical board coordinate.
widthNoNumberElement width. Defaults to 301.
heightNoNumberElement height. Defaults to 121.
themeNoStringOne of the color themes. Defaults to default.
autoHeightNoBooleanAutomatic-height setting. Defaults to true.
titleNoString, null, or localized mapElement title. Defaults to null.
contentNoString, null, or localized mapElement content. Defaults to null.
indexNoNon-negative integer or "-"Position in the board. Defaults to "-", which appends the element.

The element must fit inside the 40000 by 40000 board canvas. width and height must each be between 0 and 40000; x must be between 0 and 40000 - width, and y must be between 0 and 40000 - height.

The server generates the element ID. Relationship-managed fields such as components, attributes, outputs, covers, and linked boards are handled by their dedicated endpoints.

Provide title and content as valid Arcweave HTML content using <p>, <b>, or <code> tags.

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

Get element # GET/api/v1/{hash}/element/{elementID}

Request

http
GET /api/v1/{hash}/element/{elementID}
bash
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}"

Response

Returns 200 OK with the stored element:

json
{
  "id": "e1",
  "boardId": "b1",
  "x": 10205,
  "y": 10469,
  "width": 138,
  "height": 100,
  "theme": "cyan",
  "title": {
    "en": {
      "text": "<p>Test element 1</p>"
    }
  },
  "content": {
    "en": {
      "text": "<p>Test element 1 content</p><pre><code>custom_b1.board_var_9 = 42</code></pre>"
    }
  },
  "components": [
    {
      "id": "ref1",
      "component": "c1"
    }
  ],
  "outputs": ["con1"]
}

The response contains the stored element object.

Update element # PATCH/api/v1/{hash}/element/{elementID}

Request

http
PATCH /api/v1/{hash}/element/{elementID}
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/element/{elementID}"
json
{
  "x": 240,
  "theme": "cyan",
  "title": {
    "en": {
      "text": "<p>Updated element title</p>"
    }
  },
  "content": {
    "en": {
      "text": "<p>Updated element content.</p>"
    }
  }
}

Request fields:

PropertyRequiredTypeDescription
themeNoStringOne of the color themes. Omit to keep the current theme.
autoHeightNoBooleanUpdated automatic-height setting. If omitted, the current value is retained.
xNoNumberUpdated horizontal coordinate. If omitted, the current value is retained.
yNoNumberUpdated vertical coordinate. If omitted, the current value is retained.
widthNoNumberUpdated width. If omitted, the current value is retained.
heightNoNumberUpdated height. If omitted, the current value is retained.
titleNoString, null, or localized mapUpdated title. Path-style localized properties are supported.
contentNoString, null, or localized mapUpdated content. Path-style localized properties are supported.

Supported update fields are theme, autoHeight, x, y, width, height, title, and content. Path-style localized updates such as title/en/text are also supported. The id and relationship fields are immutable through this endpoint.

Geometry updates must keep the complete element inside the 40000 by 40000 board canvas. The server uses the element's current geometry for fields omitted from the request.

Provide title and content as valid Arcweave HTML content using <p>, <b>, or <code> tags.

Response

Returns 200 OK with project version data:

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

Reorder element # PATCH/api/v1/{hash}/element/{elementID}/index

Request

http
PATCH /api/v1/{hash}/element/{elementID}/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/element/{elementID}/index"
json
{
  "index": 0
}

Request fields:

PropertyRequiredTypeDescription
indexYesNon-negative integerNew position within the current board.

Response

Returns 200 OK with project version data:

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

Delete element # DELETE/api/v1/{hash}/element/{elementID}

Request

http
DELETE /api/v1/{hash}/element/{elementID}
bash
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}"

Deleting an element automatically deletes all attributes owned by that element.

If it is the project's starting element, Arcweave also clears the starting element to null. No replacement is selected automatically.

Response

Returns 200 OK with project version data:

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

Outputs ​

Reorder output # PATCH/api/v1/{hash}/element/{elementID}/output/{connectionID}/index

Request

http
PATCH /api/v1/{hash}/element/{elementID}/output/{connectionID}/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/element/{elementID}/output/{connectionID}/index"
json
{
  "index": 0
}

Request fields:

PropertyRequiredTypeDescription
indexYesNon-negative integerNew position within the element output list.

connectionID identifies one of the outgoing connections in the element's outputs list. Outputs can only be reordered within the same element.

Response

Returns 200 OK with project version data:

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

Starting element ​

Set the starting element # PATCH/api/v1/{hash}/starting-element

Request

The starting element is the element where the project begins when entering Play Mode.

http
PATCH /api/v1/{hash}/starting-element
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/starting-element"
json
{
  "id": "e2"
}

Request fields:

PropertyRequiredTypeDescription
idYesString or nullElement ID, or null to clear the starting element.

Set id to null to clear the starting element. The id key must always be present.

Arcweave also clears the starting element automatically when that element is deleted, including when its board or a containing folder is deleted. No replacement is selected automatically. Board deletion still requires at least one playable board to remain; clearing the starting element does not remove that requirement.

Response

Returns 200 OK with project version data:

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

Components ​

Attach component # POST/api/v1/{hash}/element/{elementID}/component

Request

http
POST /api/v1/{hash}/element/{elementID}/component
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/element/{elementID}/component"
json
{
  "componentId": "c1",
  "index": 0
}

Request fields:

PropertyRequiredTypeDescription
componentIdYesStringComponent to attach.
indexNoNon-negative integer or -Position in the attachment list. Defaults to -, which appends it.

componentId is required. index is optional.

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

Move attached component # PATCH/api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}/index

Request

http
PATCH /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}/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/element/{elementID}/component/{componentAttachmentID}/index"
json
{
  "targetElementId": "e2",
  "index": 0
}

Request fields:

PropertyRequiredTypeDescription
targetElementIdNoStringTarget element. Omit to keep the current element.
indexYesNon-negative integerNew position within the target element.

Omit targetElementId to reorder within the current element. {componentAttachmentID} is the attachment entry ID, not the component ID.

Response

Returns 200 OK with project version data:

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

Remove attached component # DELETE/api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}

Request

http
DELETE /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}
bash
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/component/{componentAttachmentID}"

Response

Returns 200 OK with project version data:

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

Attributes ​

Elements can own attributes. See Attributes for the shared board, element, and component attribute API.

Audio ​

Attach audio # POST/api/v1/{hash}/element/{elementID}/audio

Request

http
POST /api/v1/{hash}/element/{elementID}/audio
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/element/{elementID}/audio"
json
{
  "assetId": "audio2",
  "mode": "loop",
  "delay": 50,
  "index": 0
}

Request fields:

PropertyRequiredTypeDescription
assetIdYesStringAudio asset to attach.
modeNoStringPlay Mode supports once, loop, and stop. Defaults to once.
delayNoNumberPlayback delay in milliseconds. Defaults to 0.
indexNoNon-negative integer or -Position in the audio list. Defaults to -, which appends it.

assetId is required and must identify an audio asset. mode, delay, and index are optional.

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 audio attachment # PATCH/api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}

Request

http
PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}
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/element/{elementID}/audio/{audioAttachmentID}"
json
{
  "mode": "once",
  "delay": 0
}

Request fields:

PropertyRequiredTypeDescription
assetIdNoStringReplacement audio asset. If omitted, the current asset is retained.
modeNoStringPlay Mode supports once, loop, and stop. Omit to retain.
delayNoNumberPlayback delay in milliseconds. Omit to retain.

Send at least one of assetId, mode, or delay.

Response

Returns 200 OK with project version data:

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

Move audio attachment # PATCH/api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}/index

Request

http
PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}/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/element/{elementID}/audio/{audioAttachmentID}/index"
json
{
  "targetElementId": "e2",
  "index": 0
}

Request fields:

PropertyRequiredTypeDescription
targetElementIdNoStringTarget element. Omit to keep the current element.
indexYesNon-negative integerNew position within the target element.

Omit targetElementId to reorder within the current element.

Response

Returns 200 OK with project version data:

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

Remove audio attachment # DELETE/api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}

Request

http
DELETE /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}
bash
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/audio/{audioAttachmentID}"

Response

Returns 200 OK with project version data:

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

Covers ​

Set element cover # PATCH/api/v1/{hash}/element/{elementID}/cover

Request

Request fields:

FieldRequiredTypeDescription
coverYesObjectCover definition. Unknown fields are rejected.
cover.typeNoStringimage, template-image, icon, video, template-video, or youtube.
cover.idConditionalStringProject asset ID. Required when type is omitted or uses an image/video project asset.
cover.fileConditionalStringIcon filename. Required when type is icon.
cover.urlConditionalStringYouTube URL. Required when type is youtube.
cover.modeNoStringVideo playback mode: once, loop, or stop.
cover.autoplayNoBooleanWhether video playback starts automatically.
cover.showControlsNoBooleanWhether video playback controls are visible.
cover.showOptionsNoBooleanWhether video playback options are visible.
http
PATCH /api/v1/{hash}/element/{elementID}/cover
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/element/{elementID}/cover"
json
{
  "cover": {
    "id": "image_asset_id"
  }
}

Set a video cover:

json
{
  "cover": {
    "id": "video_asset_id",
    "type": "video",
    "mode": "loop",
    "autoplay": true,
    "showControls": false,
    "showOptions": true
  }
}

The referenced asset must exist and have a supported cover type. Fields are restricted by the selected cover type:

Cover typeRequired fieldsOptional fields
image, template-imageidtype
video, template-videoidtype, mode, autoplay, showControls, showOptions
icontype, fileNone
youtubetype, urlautoplay, showControls

When type is omitted, Arcweave resolves it from the asset identified by id and applies that type's allowed fields. Image covers reject video playback fields, and YouTube covers reject mode and showOptions. Mixed or unsupported fields return 400 Bad Request.

Response

Returns 200 OK with project version data:

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

Delete element cover # DELETE/api/v1/{hash}/element/{elementID}/cover

Request

http
DELETE /api/v1/{hash}/element/{elementID}/cover
bash
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/cover"

Response

Returns 200 OK with project version data:

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

Linked boards ​

Set element linked board # PATCH/api/v1/{hash}/element/{elementID}/linked-board

Request

http
PATCH /api/v1/{hash}/element/{elementID}/linked-board
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/element/{elementID}/linked-board"
json
{
  "boardId": "b1"
}

Request fields:

PropertyRequiredTypeDescription
boardIdYesStringBoard to link to the element.

The board must exist.

Response

Returns 200 OK with project version data:

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

Delete element linked board # DELETE/api/v1/{hash}/element/{elementID}/linked-board

Request

http
DELETE /api/v1/{hash}/element/{elementID}/linked-board
bash
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/element/{elementID}/linked-board"

Response

Returns 200 OK with project version data:

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

Common errors ​

StatusMeaning
400Invalid fields, malformed localized content, unsupported asset type, or missing required payload data.
403Project permission denied.
404Project, element, child entry, component, attribute, asset, board, or output not found.
409The board or target resource changed before the command was applied.