# Components

Source: https://docs.arcweave.com/rest-api/components
Section: REST API
Description: REST API endpoints for components, component folders, and covers

Component endpoints manage the component tree and component covers. Component attributes use the dedicated [attribute endpoints](https://docs.arcweave.com/rest-api/attributes).

## Endpoints

Context: Arcweave docs > REST API > Components > Endpoints

### Get components

Context: Arcweave docs > REST API > Components > Endpoints > Get components

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

**Request**

```http title="HTTP"
GET /api/v1/{hash}/component
```

```bash title="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:

```json
[
  {
    "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

Context: Arcweave docs > REST API > Components > Endpoints > Get component

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

**Request**

```http title="HTTP"
GET /api/v1/{hash}/component/{componentID}
```

```bash title="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:

```json
{
  "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

Context: Arcweave docs > REST API > Components > Endpoints > Create component or folder

`POST /api/v1/{hash}/component`

**Request**

```http title="HTTP"
POST /api/v1/{hash}/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/component"
```

Create a component:

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

Create a folder:

```json
{
  "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](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | 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](https://docs.arcweave.com/rest-api/localization) 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](https://docs.arcweave.com/rest-api/attributes#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:

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

### Rename component

Context: Arcweave docs > REST API > Components > Endpoints > Rename component

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

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/component/{componentID}
```

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

```json
{
  "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](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | Updated name. Path-style localized name properties are also supported. |

The endpoint supports `name` and [path-style localized name fields](https://docs.arcweave.com/rest-api/localization#update-one-translated-field), 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](https://docs.arcweave.com/rest-api/localization). Blank `name` values follow the same rules as in [Create component or folder](https://docs.arcweave.com/rest-api/components#create-component-or-folder).

**Response**

Returns `200 OK` with project version data:

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

### Move or reorder component

Context: Arcweave docs > REST API > Components > Endpoints > Move or reorder component

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

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/component/{componentID}/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/component/{componentID}/index"
```

```json
{
  "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:

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

### Delete component

Context: Arcweave docs > REST API > Components > Endpoints > Delete component

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

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/component/{componentID}
```

```bash title="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](https://docs.arcweave.com/rest-api/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:

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

### Set component cover

Context: Arcweave docs > REST API > Components > Endpoints > Set component cover

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

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/component/{componentID}/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/component/{componentID}/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`, 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](https://docs.arcweave.com/project-tools/icon-library) path in `artist/icon-name` form, such as `Arcweave/star`. Required when `type` is `icon`. |

Set an icon cover:

```json
{
  "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:

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

### Delete component cover

Context: Arcweave docs > REST API > Components > Endpoints > Delete component cover

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

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/component/{componentID}/cover
```

```bash title="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:

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

## Common errors

Context: Arcweave docs > REST API > Components > 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](https://docs.arcweave.com/rest-api/localization#unknown-locale-errors) was supplied, or the component tree or target changed before the command was applied. |