Components

Component endpoints manage the component tree and component covers. Component attributes use the dedicated attribute endpoints.

Endpoints

Get components # GET/api/v1/{hash}/component

Request

HTTP

GET /api/v1/{hash}/component

curl

curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/component"

Response

Returns 200 OK with a compact representation of the complete component tree:

[
  {
    "id": "c0",
    "name": "Root",
    "type": "folder",
    "parentId": null,
    "children": ["component_1", "characters_folder"]
  },
  {
    "id": "component_1",
    "name": "Guard",
    "type": "component",
    "parentId": "c0",
    "children": []
  },
  {
    "id": "characters_folder",
    "name": "Characters",
    "type": "folder",
    "parentId": "c0",
    "children": []
  }
]

Every entry contains id, name, type, parentId, and children. Folder entries, including the internal root, use type: "folder"; regular components use type: "component". Names are returned as strings using the project's default locale and available locale fallbacks, or null when no name text is available.

Entries are not listed in tree order. A folder's children lists its direct child components and folders in display order; regular components return []. Use parentId and children to rebuild the hierarchy.

Get component # GET/api/v1/{hash}/component/{componentID}

Request

HTTP

GET /api/v1/{hash}/component/{componentID}

curl

curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}"

Response

Returns 200 OK with the stored component or folder:

{
  "id": "c2",
  "customId": "component2",
  "parentId": "c0",
  "name": {
    "en": {
      "text": "Component 2"
    }
  },
  "attributes": null
}

The response includes parentId unless the requested item is the internal root. Regular components include name, customId, attributes (attribute IDs or null), and assets.cover when a cover is set. Folders include children (child IDs) and name. The internal root has root: true and no stored name.

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

Request

HTTP

POST /api/v1/{hash}/component

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/component"

Create a component:

{
  "name": "Guard",
  "parentId": "characters_folder",
  "index": 1
}

Create a folder:

{
  "type": "folder",
  "name": "Characters",
  "index": 0
}

Property	Required	Type	Description
type	No	String	component or folder. Defaults to component.
name	No	String, null, or localized map	Defaults to Untitled component for components or New folder for folders.
parentId	No	String or null	Parent component folder. Defaults to the root component container.
index	No	Non-negative integer or "-"	Position in the parent folder. Defaults to "-", which appends the item.

The target parent must exist and must be a folder. Regular components cannot contain child components.

Passing name as a string or null targets the project's main language. Locale maps target only the supplied, already configured languages. See Localized content for the request formats and locale prerequisites. A blank or whitespace-only main-language name is saved as Untitled component; blank names in other languages are saved as null.

For regular components, Arcweave generates a unique customId from the main-language name, avoiding existing board and component custom IDs and reserved identifiers. This ID supports component variable attributes. Folders do not get a customId. The create and rename endpoints do not accept a custom customId, and renaming does not change it.

Response

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

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

Rename component # PATCH/api/v1/{hash}/component/{componentID}

Request

HTTP

PATCH /api/v1/{hash}/component/{componentID}

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/component/{componentID}"

{
  "name/en/text": "Updated Guard"
}

Request fields:

Property	Required	Type	Description
name	Yes, unless a path-style name field is sent	String, null, or localized map	Updated name. Path-style localized name properties are also supported.

The endpoint supports name and path-style localized name fields, such as name/fr/text. Other component properties are managed through dedicated endpoints. Renaming also updates component mention labels.

Passing name as a string or null changes only the main language. A locale map updates only its supplied languages and preserves the others. All locale codes must already exist in the project; see Localized content. Blank name values follow the same rules as in Create component or folder.

Response

Returns 200 OK with project version data:

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

Move or reorder component # PATCH/api/v1/{hash}/component/{componentID}/index

Request

HTTP

PATCH /api/v1/{hash}/component/{componentID}/index

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/component/{componentID}/index"

{
  "parentId": "characters_folder",
  "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.
• Omit parentId to reorder within the current folder.
• Use "parentId": null to move to the root component container.
• The target must be a component folder.
• A folder cannot be moved into itself or one of its descendants.
• The root component container cannot be moved.

Response

Returns 200 OK with project version data:

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

Delete component # DELETE/api/v1/{hash}/component/{componentID}

Request

HTTP

DELETE /api/v1/{hash}/component/{componentID}

curl

curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}"

Deleting a component automatically deletes all attributes owned by that component. Deleting a folder deletes its full subtree and the attributes owned by every component in that subtree. Arcweave also removes the deleted components from element component attachments and component-list attribute values, and converts their mentions to plain text.

The root component container cannot be deleted.

Response

Returns 200 OK with project version data:

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

Set component cover # PATCH/api/v1/{hash}/component/{componentID}/cover

Request

HTTP

PATCH /api/v1/{hash}/component/{componentID}/cover

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/component/{componentID}/cover"

{
  "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, or icon.
cover.id	Conditional	String	Project image asset ID. Required when type is omitted, image, or template-image.
cover.file	Conditional	String	Icon library path in artist/icon-name form, such as Arcweave/star. Required when type is icon.

Set an icon cover:

{
  "cover": {
    "type": "icon",
    "file": "Arcweave/star"
  }
}

Folders cannot have covers. Project asset covers must identify image assets. The accepted cover fields depend on its type: image and template-image accept only id and type; icon accepts only type and file. When id is supplied, Arcweave stores the referenced asset's type (image or template-image), replacing any type in the request. Mixing fields from different cover types returns 400 Bad Request.

The new cover replaces the component's existing cover.

Response

Returns 200 OK with project version data:

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

Delete component cover # DELETE/api/v1/{hash}/component/{componentID}/cover

Request

HTTP

DELETE /api/v1/{hash}/component/{componentID}/cover

curl

curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/component/{componentID}/cover"

Response

Returns 200 OK with project version data:

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

Common errors

Status	Meaning
400	Invalid component data, malformed localized name, folder cover mutation, non-image cover asset, root mutation, non-folder parent, or recursive move.
403	Project permission denied.
404	Project, component, parent, or cover asset not found.
409	An unknown locale was supplied, or the component tree or target changed before the command was applied.