# Elements Source: https://docs.arcweave.com/rest-api/elements Section: REST API Description: REST API endpoints for elements and their components, attributes, audio, and covers Element endpoints manage element content and ordering, attached components, attributes, audio, covers, outputs, and the project's starting element. ## Element endpoints Context: Arcweave docs > REST API > Elements > Element endpoints ### Create element Context: Arcweave docs > REST API > Elements > Element endpoints > Create element `POST /api/v1/{hash}/element` **Request** ```http title="HTTP" POST /api/v1/{hash}/element ``` ```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/element" ``` ```json { "boardId": "b1", "x": 200, "y": 300, "width": 320, "height": 180, "title": "

Opening

", "content": "

The story begins.

" } ``` | Property | Required | Type | Description | | ------------ | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `boardId` | Yes | String | Board that will contain the element. | | `x` | Yes | Number | Horizontal board coordinate. | | `y` | Yes | Number | Vertical board coordinate. | | `width` | No | Number | Element width. Defaults to `301`. | | `height` | No | Number | Element height. Defaults to `121`. | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`. | | `autoHeight` | No | Boolean | Automatic-height setting. Defaults to `true`. | | `title` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Element title. Defaults to `null`. | | `content` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Element content. Defaults to `null`. | | `index` | No | Non-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. New elements start with `components: null` and `outputs: null`, matching elements created in the editor. MCP element creation uses the same defaults. The server sets these fields; do not include them in create or update requests. Provide `title` and `content` as [valid rich text HTML](https://docs.arcweave.com/rest-api/rich-text#supported-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](https://docs.arcweave.com/rest-api/localization) 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 Context: Arcweave docs > REST API > Elements > Element endpoints > Get element `GET /api/v1/{hash}/element/{elementID}` **Request** ```http title="HTTP" GET /api/v1/{hash}/element/{elementID} ``` ```bash title="curl" 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": "

Test element 1

" } }, "content": { "en": { "text": "

Test element 1 content

custom_b1.board_var_9 = 42
" } }, "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, including in existing or imported elements. Treat `null`, an empty array, or a missing field as empty: - `components`: component attachments. Each `id` is the attachment ID used by the [component attachment endpoints](https://docs.arcweave.com/rest-api/elements#components). - `attributes`: IDs of the element's [attributes](https://docs.arcweave.com/rest-api/attributes). - `assets.audio`: audio attachments with `id`, `asset`, `mode`, and `delay`, plus `volume`, `fadeIn`, `fadeOut`, and `autoStopOnExit` when set. Each `id` is the attachment ID used by the [audio endpoints](https://docs.arcweave.com/rest-api/elements#audio). - `assets.cover`: the element's [cover](https://docs.arcweave.com/rest-api/elements#covers). - `outputs`: IDs of the element's outgoing connections. ### Update element Context: Arcweave docs > REST API > Elements > Element endpoints > Update element `PATCH /api/v1/{hash}/element/{elementID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID} ``` ```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/element/{elementID}" ``` ```json { "x": 240, "theme": "cyan", "title": { "en": { "text": "

Updated element title

" } }, "content": { "en": { "text": "

Updated element content.

" } } } ``` Request fields: | Property | Required | Type | Description | | ------------ | -------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `theme` | No | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. | | `autoHeight` | No | Boolean | Updated automatic-height setting. If omitted, the current value is retained. | | `x` | No | Number | Updated horizontal coordinate. If omitted, the current value is retained. | | `y` | No | Number | Updated vertical coordinate. If omitted, the current value is retained. | | `width` | No | Number | Updated width. If omitted, the current value is retained. | | `height` | No | Number | Updated height. If omitted, the current value is retained. | | `title` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated title. Path-style localized properties are supported. | | `content` | No | String, `null`, or [localized map](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated content. Path-style localized properties are supported. | Supported update fields are `theme`, `autoHeight`, `x`, `y`, `width`, `height`, `title`, and `content`. Path-style [localized updates](https://docs.arcweave.com/rest-api/localization#update-one-translated-field) 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](https://docs.arcweave.com/rest-api/rich-text#supported-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](https://docs.arcweave.com/rest-api/elements#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](https://docs.arcweave.com/rest-api/localization) 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 Context: Arcweave docs > REST API > Elements > Element endpoints > Reorder element `PATCH /api/v1/{hash}/element/{elementID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/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/element/{elementID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | -------------------------------------- | | `index` | Yes | Non-negative integer | New position within the current board. | **Response** Returns `200 OK` with project version data: ```json { "version": 12, "newVersion": 13, "versionTime": ["1720788000", "123456"] } ``` ### Delete element Context: Arcweave docs > REST API > Elements > Element endpoints > Delete element `DELETE /api/v1/{hash}/element/{elementID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID} ``` ```bash title="curl" 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](https://docs.arcweave.com/rest-api/attributes) owned by that element. [Jumpers](https://docs.arcweave.com/rest-api/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 Context: Arcweave docs > REST API > Elements > Outputs ### Reorder output Context: Arcweave docs > REST API > Elements > Outputs > Reorder output `PATCH /api/v1/{hash}/element/{elementID}/output/{connectionID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/output/{connectionID}/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/element/{elementID}/output/{connectionID}/index" ``` ```json { "index": 0 } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | -------------------- | -------------------------------------------- | | `index` | Yes | Non-negative integer | New 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 Context: Arcweave docs > REST API > Elements > Starting element The [starting element](https://docs.arcweave.com/project-tools/play-mode/using-play-mode#set-play-mode-start) is the element where the project begins when entering Play Mode. ### Get the starting element Context: Arcweave docs > REST API > Elements > Starting element > 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](https://docs.arcweave.com/rest-api/overview#permissions). **Request** ```http title="HTTP" GET /api/v1/{hash}/starting-element ``` ```bash title="curl" 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](https://docs.arcweave.com/rest-api/overview#rate-limits), 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](https://docs.arcweave.com/rest-api/elements#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": "

Test element 1

" } }, "content": { "en": { "text": "

Test element 1 content

custom_b1.board_var_9 = 42
" } }, "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](https://docs.arcweave.com/rest-api/elements#set-the-starting-element). Reading it does not change the selection or add a project command-history entry. ### Set the starting element Context: Arcweave docs > REST API > Elements > Starting element > Set the starting element `PATCH /api/v1/{hash}/starting-element` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/starting-element ``` ```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/starting-element" ``` ```json { "id": "e2" } ``` Request fields: | Property | Required | Type | Description | | -------- | -------- | ---------------- | ---------------------------------------------------- | | `id` | Yes | String or `null` | Element 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](https://docs.arcweave.com/rest-api/elements#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](https://docs.arcweave.com/rest-api/boards#delete-board) 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 Context: Arcweave docs > REST API > Elements > Components ### Attach component Context: Arcweave docs > REST API > Elements > Components > Attach component `POST /api/v1/{hash}/element/{elementID}/component` **Request** ```http title="HTTP" POST /api/v1/{hash}/element/{elementID}/component ``` ```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/element/{elementID}/component" ``` ```json { "componentId": "c1", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ------------- | -------- | --------------------------- | ------------------------------------------------------------------------- | | `componentId` | Yes | String | Regular component to attach. Folders and root containers are not allowed. | | `index` | No | Non-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 Context: Arcweave docs > REST API > Elements > Components > Move attached component `PATCH /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}/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/element/{elementID}/component/{componentAttachmentID}/index" ``` ```json { "targetElementId": "e2", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ----------------- | -------- | -------------------- | ------------------------------------------------- | | `targetElementId` | No | String | Target element. Omit to keep the current element. | | `index` | Yes | Non-negative integer | New 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 Context: Arcweave docs > REST API > Elements > Components > Remove attached component `DELETE /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/component/{componentAttachmentID} ``` ```bash title="curl" 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 Context: Arcweave docs > REST API > Elements > Attributes Elements can own attributes. See [Attributes](https://docs.arcweave.com/rest-api/attributes) for the shared board, element, and component attribute API. ## Audio Context: Arcweave docs > REST API > Elements > Audio ### Attach audio Context: Arcweave docs > REST API > Elements > Audio > Attach audio `POST /api/v1/{hash}/element/{elementID}/audio` **Request** ```http title="HTTP" POST /api/v1/{hash}/element/{elementID}/audio ``` ```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/element/{elementID}/audio" ``` ```json { "assetId": "audio2", "mode": "loop", "delay": 50, "volume": 0.6, "fadeIn": 500, "fadeOut": 1000, "autoStopOnExit": true, "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ---------------- | -------- | --------------------------- | ----------------------------------------------------------------------------------- | | `assetId` | Yes | String | Audio asset to attach. | | `mode` | No | String | Playback mode: `once`, `loop`, or `stop`. Defaults to `once`. | | `delay` | No | Number | Playback delay in milliseconds. Defaults to `0`. | | `volume` | No | Number | Volume override from `0` to `1`. Omit to use the asset's volume. | | `fadeIn` | No | Number | Fade-in override in milliseconds. Omit to use the asset's value. | | `fadeOut` | No | Number | Fade-out override in milliseconds. Omit to use the asset's value. | | `autoStopOnExit` | No | Boolean | When `true`, stops the clip when Play Mode leaves the element. Defaults to `false`. | | `index` | No | Non-negative integer or `-` | Position in the audio list. Defaults to `-`, which appends it. | `assetId` is required and must identify an audio asset. All other fields are optional. `delay`, `fadeIn`, and `fadeOut` must be zero or more. In Play Mode, `once` plays the clip once, `loop` repeats it, and `stop` stops all playing instances of the clip, fading them out over the `stop` reference's fade-out duration. See [Audio reference settings](https://docs.arcweave.com/project-items/assets/audio#audio-reference-settings). **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 Context: Arcweave docs > REST API > Elements > Audio > Update audio attachment `PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID} ``` ```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/element/{elementID}/audio/{audioAttachmentID}" ``` ```json { "mode": "once", "delay": 0, "fadeOut": null } ``` Request fields: | Property | Required | Type | Description | | ---------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------- | | `assetId` | No | String | Replacement audio asset. If omitted, the current asset is retained. | | `mode` | No | String | Playback mode: `once`, `loop`, or `stop`. Omit to retain. | | `delay` | No | Number | Playback delay in milliseconds. Omit to retain. | | `volume` | No | Number or `null` | Volume override from `0` to `1`. Use `null` to use the asset's volume again; omit to retain. | | `fadeIn` | No | Number or `null` | Fade-in override in milliseconds. Use `null` to use the asset's value again; omit to retain. | | `fadeOut` | No | Number or `null` | Fade-out override in milliseconds. Use `null` to use the asset's value again; omit to retain. | | `autoStopOnExit` | No | Boolean | Whether to stop the clip when Play Mode leaves the element. Omit to retain. | Send at least one of these fields. `{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 Context: Arcweave docs > REST API > Elements > Audio > Move audio attachment `PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}/index` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}/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/element/{elementID}/audio/{audioAttachmentID}/index" ``` ```json { "targetElementId": "e2", "index": 0 } ``` Request fields: | Property | Required | Type | Description | | ----------------- | -------- | -------------------- | ------------------------------------------------- | | `targetElementId` | No | String | Target element. Omit to keep the current element. | | `index` | Yes | Non-negative integer | New 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 Context: Arcweave docs > REST API > Elements > Audio > Remove audio attachment `DELETE /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID}` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/audio/{audioAttachmentID} ``` ```bash title="curl" 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 Context: Arcweave docs > REST API > Elements > Covers ### Set element cover Context: Arcweave docs > REST API > Elements > Covers > Set element cover `PATCH /api/v1/{hash}/element/{elementID}/cover` **Request** ```http title="HTTP" PATCH /api/v1/{hash}/element/{elementID}/cover ``` ```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/element/{elementID}/cover" ``` ```json { "cover": { "id": "image_asset_id" } } ``` Request fields: | Property | Required | Type | Description | | -------------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `cover` | Yes | Object | Cover definition. Unknown fields are rejected. | | `cover.type` | No | String | `image`, `template-image`, `icon`, `video`, `template-video`, or `youtube`. | | `cover.id` | Conditional | String | Project asset ID. Required when `type` is omitted or uses an image/video project asset. | | `cover.file` | Conditional | String | [Icon library](https://docs.arcweave.com/project-tools/icon-library) path in `artist/icon-name` form, such as `Arcweave/star`. Required when `type` is `icon`. | | `cover.url` | Conditional | String | YouTube URL. Required when `type` is `youtube`. | | `cover.mode` | No | String | Video playback mode: `once`, `loop`, or `stop`. | | `cover.autoplay` | No | Boolean | Whether video playback starts automatically. | | `cover.showControls` | No | Boolean | Whether video playback controls are visible. | | `cover.showOptions` | No | Boolean | Whether 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 type | Required fields | Optional fields | | ------------------------- | --------------- | --------------------------------------------------------- | | `image`, `template-image` | `id` | `type` | | `video`, `template-video` | `id` | `type`, `mode`, `autoplay`, `showControls`, `showOptions` | | `icon` | `type`, `file` | None | | `youtube` | `type`, `url` | `autoplay`, `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 Context: Arcweave docs > REST API > Elements > Covers > Delete element cover `DELETE /api/v1/{hash}/element/{elementID}/cover` **Request** ```http title="HTTP" DELETE /api/v1/{hash}/element/{elementID}/cover ``` ```bash title="curl" 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 Context: Arcweave docs > REST API > Elements > Common errors | Status | Meaning | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid fields, malformed localized content, invalid Arcscript, board folder target, unsupported asset type, component folder/root attachment, or missing required payload data. | | `403` | Project permission denied. | | `404` | Project, element, target element, component, asset, component or audio attachment, or output not found. | | `409` | An [unknown locale](https://docs.arcweave.com/rest-api/localization#unknown-locale-errors) 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. |