> For the complete documentation index, see [llms.txt](https://docs.archisketch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archisketch.com/guide/dev-en/api-sdk/api-integration/3d-product-integration/component.md).

# Register Component

This guide explains how to create and manage components based on modeling.

A component is a unit of parts configured based on modeling. Use the modeling ID created in the previous step to create a component. The generated component ID will be used later for [Product creation](/guide/dev-en/api-sdk/api-integration/3d-product-integration/product.md).

You must include the `X-API-KEY` in the header of all API requests. Refer to the ["How to Use the API"](/guide/dev-en/api-sdk/how-to-use.md) guide for instructions on how to issue it.

```http
X-API-KEY: {x-api-key}
```

## Create Component

**POST** `/api/v1/components`

{% stepper %}
{% step %}

### Prepare Required Information

The following information is required when creating a component:

* `modelingId`: The modeling ID created in "Registering Modeling".
* `dimension`: The actual dimensions of the component (in mm or inches).
* `translatedNames`: A list of multilingual names (language code + name).

| Field           | Type    | Required | Description                                  |
| --------------- | ------- | -------- | -------------------------------------------- |
| name            | string  | ✅        | Name                                         |
| translatedNames | array   | ✅        | Multilingual name list                       |
| dimension       | object  | ✅        | Dimensions (in mm/inch)                      |
| isFinal         | boolean | ✅        | Whether it is a final part                   |
| childComponents | array   | ✅        | Child component list                         |
| codeRelations   | array   | ✅        | Code relation list                           |
| images          | array   | ✅        | Image URL list (can be an empty array `[]`)  |
| modelingId      | string  |          | Modeling ID                                  |
| code            | string  |          | Code                                         |
| brandCode       | string  |          | Brand code                                   |
| sku             | string  |          | SKU                                          |
| retailPrice     | object  |          | Retail price                                 |
| factoryPrice    | object  |          | Factory price                                |
| isPersonal      | boolean |          | Whether it is uploaded to a personal library |
| category        | object  |          | Category                                     |
| {% endstep %}   |         |          |                                              |

{% step %}

### Send Request

```json
POST /api/v1/components
X-API-KEY: {x-api-key}

{
  "name": "Sofa",
  "translatedNames": [
    { "code": "en", "value": "Sofa" },
    { "code": "ko", "value": "소파" }
  ],
  "dimension": {
    "mm": {
      "width": 900,
      "depth": 800,
      "height": 750
    }
  },
  "isFinal": true,
  "images": ["https://..."],
  "childComponents": [],
  "codeRelations": [],
  "modelingId": "mdl_abc123"
}
```

{% endstep %}

{% step %}

### Check Response

```json
{
  "result": "SUCCESS",
  "data": {
    "id": "cmp_def456",
    "enterpriseId": "ENT_ABC123",
    "userId": "usr_xyz",
    "name": "Sofa",
    "translatedNames": [
      { "code": "en", "value": "Sofa" },
      { "code": "ko", "value": "소파" }
    ],
    "modelingId": "mdl_abc123",
    "isFinal": true,
    "isRaw": false,
    "dimension": {
      "mmWidth": 900,
      "mmDepth": 800,
      "mmHeight": 750,
      "inchWidth": 35.4,
      "inchDepth": 31.5,
      "inchHeight": 29.5
    },
    "previewImage": null,
    "images": [],
    "hdViewerAssets": [],
    "childComponents": [],
    "categories": [],
    "createdAt": "2026-04-04T10:01:00Z",
    "updatedAt": "2026-04-04T10:01:00Z"
  }
}
```

> 📌 Note: Please save the `data.id` value. It will be used for [Product Creation](/guide/dev-en/api-sdk/api-integration/3d-product-integration/product.md) in the next step.
> {% endstep %}
> {% endstepper %}

## Get Component List

**GET** `/api/v1/components`

| Parameter  | Type    | Required | Description                 |
| ---------- | ------- | -------- | --------------------------- |
| offset     | integer | ✅        | Page number (starts from 0) |
| limit      | integer | ✅        | Page size (1–100)           |
| categoryId | string  |          | Category ID filter          |
| name       | string  |          | Name search keyword         |
| sortType   | string  |          | Sorting criteria            |

```http
GET /api/v1/components?offset=0&limit=20
X-API-KEY: {x-api-key}
```

## Get Single Component

**GET** `/api/v1/components/{id}`

```http
GET /api/v1/components/cmp_def456
X-API-KEY: {x-api-key}
```

## Update Component Basic Info

**PATCH** `/api/v1/components/{id}`

| Field           | Type   | Required | Description       |
| --------------- | ------ | -------- | ----------------- |
| name            | string | ✅        | Name              |
| translatedNames | array  | ✅        | Multilingual name |
| dimension       | object | ✅        | Dimensions        |

## Get Flat BOM

**GET** `/api/v1/components/{id}/bom`

Retrieve the flattened BOM (Bill of Materials) structure of the component. If a component consists of multiple sub-parts, you can check the entire structure at once.

```http
GET /api/v1/components/cmp_def456/bom
X-API-KEY: {x-api-key}
```

## Upload Assets

**POST** `/api/v1/components/{id}/assets`

Upload asset files, such as images, to the component.

| Field     | Type   | Required | Description |
| --------- | ------ | :------: | ----------- |
| assetType | string |     ✅    | Asset type  |
| files     | array  |     ✅    | File list   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.archisketch.com/guide/dev-en/api-sdk/api-integration/3d-product-integration/component.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.