> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assets

> Manage assets in Cognite Data Fusion (CDF).

<Badge color="orange">Legacy data modeling</Badge>

<Note>
  This resource is part of the **asset-centric** data model (legacy).

  * **New projects**: Model assets using the **[data modeling](/api-reference/concepts/20230101/data-modeling)** service—with the [CogniteAsset](/cdf/dm/dm_reference/dm_core_data_model#asset) concept, asset hierarchies, and greater flexibility.
  * **Existing projects**: This resource remains fully supported for maintaining legacy applications.
</Note>

**Assets** represent digital representations of objects or groups of objects from the physical world, such as water pumps, motors, machine rooms, or entire plants.

Assets **connect related data from different sources** and are core to identifying all the data relevant to an entity (**contextualization**) in CDF. You can connect each asset to many resources and resource types. For example, you can connect a pump asset to [time series](/api-reference/concepts/20230101/time-series) that measure pressure, to [events](/api-reference/concepts/20230101/events) that record maintenance operations, and to [files](/api-reference/concepts/20230101/files) with pump diagrams.

Assets are organized in **hierarchies**. For example, a `Pump` asset can be part of a `System` asset, which is part of a `Plant` asset. An asset can have a parent asset and multiple child assets, but an asset can only have one parent. At the top of each hierarchy is a **root asset**. Each project can have several root assets, and all assets under the root asset must have a parent asset.

## Structure an asset hierarchy

This example shows you how to structure the asset hierarchy for the fictional **SYSTEM 11**:

```txt theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
SYSTEM 11
└───Pump
│   └───Heating cable
└───Pump
```

Outlined in CSV format, the system looks like this:

| name          | description               | externalId     | parentExternalId |
| ------------- | ------------------------- | -------------- | ---------------- |
| SYSTEM 11     | Sea water system          | SYSTEM\_11     |                  |
| Pump          | Main pump for system 11   | PUMP\_A        | SYSTEM\_11       |
| Heating cable | Heating cable for pump A  | HEATING\_CABLE | PUMP\_A          |
| Pump          | Backup pump for system 11 | PUMP\_B        | SYSTEM\_11       |

You can post all assets in one request when you structure an asset hierarchy.

<AccordionGroup>
  <Accordion title="Example: create an asset hierarchy">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    POST /api/v1/projects/<project>/assets
    Host: api.cognitedata.com
    ```

    Request body:

    ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "items": [
        {
          "name": "SYSTEM 11",
          "description": "Sea water system",
          "externalId": "SYSTEM_11"
        },
        {
          "name": "Pump",
          "description": "Main pump for system 11",
          "externalId": "PUMP_A",
          "parentExternalId": "SYSTEM_11"
        },
        {
          "name": "Pump",
          "externalId": "Pump_B",
          "description": "Backup pump for system 11",
          "parentExternalId": "SYSTEM_11"
        },
        {
          "name": "Heating cable",
          "externalId": "HEATING_CABLE",
          "description": "Heating cable for pump A",
          "parentExternalId": "PUMP_A"
        }
      ]
    }
    ```

    The response body will look similar to this:

    ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "items": [
        {
          "externalId": "SYSTEM_11",
          "name": "SYSTEM 11",
          "description": "Sea water system",
          "metadata": {},
          "id": 4181031623333192,
          "createdTime": 1562764416913,
          "lastUpdatedTime": 1562764416913,
          "rootId": 4181031623333192
        },
        {
          "externalId": "PUMP_A",
          "name": "Pump",
          "parentId": 4181031623333192,
          "description": "Main pump for system 11",
          "metadata": {},
          "id": 2975365566518130,
          "createdTime": 1562764416913,
          "lastUpdatedTime": 1562764416913,
          "rootId": 4181031623333192
        },
        {
          "externalId": "Pump_B",
          "name": "Pump",
          "parentId": 4181031623333192,
          "description": "Backup pump for system 11",
          "metadata": {},
          "id": 1366019363753734,
          "createdTime": 1562764416913,
          "lastUpdatedTime": 1562764416913,
          "rootId": 4181031623333192
        },
        {
          "externalId": "HEATING_CABLE",
          "name": "Heating cable",
          "parentId": 2975365566518130,
          "description": "Heating cable for pump A",
          "metadata": {},
          "id": 3816457134628307,
          "createdTime": 1562764416913,
          "lastUpdatedTime": 1562764416913,
          "rootId": 4181031623333192
        }
      ]
    }
    ```

    In addition to `externalId`, you get a unique `id` field and value. References within CDF use that id, so `parentExternalId` is translated into that new unique identifier. The `rootId` field gives you the id of the root asset.
  </Accordion>
</AccordionGroup>

## Rate and concurrency limits

For Assets rate and concurrency limits, see [API rate limits](/api-reference/concepts/20230101/rate-limits#assets).