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.

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
}

Regular components include their name, custom ID, attribute IDs, and optional cover. Folders include child IDs.

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 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.

Arcweave generates a unique customId from the component name, avoiding existing board and component IDs and reserved identifiers. This ID supports component variable attributes. The create and rename endpoints do not accept a custom customId.

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	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. Other component properties are managed through dedicated endpoints. Renaming also updates component mention labels.

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. Related component references and mentions are also removed.

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 filename. Required when type is icon.

Set an icon cover:

{
  "cover": {
    "type": "icon",
    "file": "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. If type is omitted, supply id and Arcweave resolves the image asset type. Mixing fields from different cover types returns 400 Bad Request.

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, root mutation, non-folder parent, or recursive move.
403	Project permission denied.
404	Project, component, parent, or cover asset not found.
409	Component tree or target changed before the command was applied.