Arcweave Documentation

Appearance

Elements ​

Element endpoints manage element content and ordering, attached components, attributes, audio, covers, 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, and covers are handled by their dedicated endpoints.

Provide title and content as valid rich text HTML. Element content supports blockquotes and Arcscript code blocks; titles support neither. Inline code is not supported.

Arcweave validates Arcscript code blocks in content, including whether the variables, attributes, and elements they reference exist. Invalid Arcscript returns 400 Bad Request with the title Bad Request - invalid Arcscript, and the request is not applied.

A string or null updates only the project's main language. Locale maps update only the supplied, already configured languages; see Localized content for examples and error handling.

If boardId does not exist, the request returns 409 Conflict with conflictType: "missing_parent". A board folder returns 400 Bad Request.

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 and its boardId. Relationship fields can be absent or null when empty:

  • components: component attachments. Each id is the attachment ID used by the component attachment endpoints.
  • attributes: IDs of the element's attributes.
  • assets.audio: audio attachments with id, asset, mode, and delay. Each id is the attachment ID used by the audio endpoints.
  • assets.cover: the element's cover.
  • outputs: IDs of the element's outgoing connections.

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 rich text HTML. Element content supports blockquotes and Arcscript code blocks; titles support neither. Inline code is not supported. Arcscript in content is validated as described in Create element.

A string or null updates only the project's main language. Locale maps update only the supplied, already configured languages; see Localized content for examples and error handling.

If the element does not exist, the request returns 409 Conflict with conflictType: "missing_target".

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 also deletes its incoming and outgoing connections and all attributes owned by that element. Jumpers that target the element remain, with their elementId cleared to null. Mentions of the element elsewhere in the project are converted to plain text.

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

If the element does not exist, the request returns 409 Conflict with conflictType: "missing_target".

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 ​

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

Get the starting element # GET/api/v1/{hash}/starting-element

Retrieve the project's current starting element without exporting the project or knowing the element ID first.

The key needs Read projects (project:read), and its owner needs View projects list permission for the target project in the key's Team workspace. See Permissions.

Request

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

The unversioned /api/{hash}/starting-element route is an alias. Use /api/v1 for new integrations.

This request counts toward the overall workspace API quota, but does not consume the import/export quota or require an export feature.

Response

Returns 200 OK with the starting element's ID and full stored element. The element object has the same shape as Get element, including boardId, localized text, and attachment references:

json
{
  "elementId": "e1",
  "element": {
    "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"]
  }
}

When no starting element is configured, the endpoint still returns 200 OK, with both fields set to null:

json
{
  "elementId": null,
  "element": null
}

The response reflects the current selection across all boards, including recent changes made through Set the starting element. Reading it does not change the selection or add a project command-history entry.

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

Request

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. Use Get the starting element to read the current selection or verify an update.

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
componentIdYesStringRegular component to attach. Folders and root containers are not allowed.
indexNoNon-negative integer or -Position in the attachment list. Defaults to -, which appends it.

componentId must identify a regular component. Component folders and root containers return 400 Bad Request; regular components located inside folders can be attached. index is optional.

Response

Returns 201 Created with project version data. The id is the new attachment ID, used as {componentAttachmentID} in the endpoints below:

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.
modeNoStringPlayback mode: once, loop, or 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.

In Play Mode, once plays the clip once, loop repeats it, and stop stops all playing instances of the clip.

Response

Returns 201 Created with project version data. The id is the new audio attachment ID, used as {audioAttachmentID} in the endpoints below:

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.
modeNoStringPlayback mode: once, loop, or stop. Omit to retain.
delayNoNumberPlayback delay in milliseconds. Omit to retain.

Send at least one of assetId, mode, or delay. {audioAttachmentID} is the attachment entry ID from the element's assets.audio list, not the asset ID.

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. {audioAttachmentID} is the attachment entry ID, not the asset ID.

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

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

Request fields:

PropertyRequiredTypeDescription
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 library path in artist/icon-name form, such as Arcweave/star. 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.

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 id is supplied, Arcweave applies the allowed fields of the referenced asset's type and stores that type, replacing any type in the request. Image and template-image assets keep their type; video and template-video assets are stored as video. If you also send type, the fields must be valid for that type as well. Image covers reject video playback fields, and YouTube covers reject mode and showOptions. Mixed or unsupported fields return 400 Bad Request.

The new cover replaces the element's existing cover, including any playback options you omit.

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

Common errors ​

StatusMeaning
400Invalid fields, malformed localized content, invalid Arcscript, board folder target, unsupported asset type, component folder/root attachment, or missing required payload data.
403Project permission denied.
404Project, element, target element, component, asset, component or audio attachment, or output not found.
409An unknown locale was supplied, the board to create in or the element to update or delete does not exist, or the board or target resource changed before the command was applied.