Skip to main content

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.

Legacy data modeling
This resource is part of the asset-centric data model (legacy).
  • New projects: Model assets using the data modeling service—with the CogniteAsset concept, asset hierarchies, and greater flexibility.
  • Existing projects: This resource remains fully supported for maintaining legacy applications.
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 that measure pressure, to events that record maintenance operations, and to 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: 
SYSTEM 11
└───Pump
│   └───Heating cable
└───Pump
Outlined in CSV format, the system looks like this:
namedescriptionexternalIdparentExternalId
SYSTEM 11Sea water systemSYSTEM_11
PumpMain pump for system 11PUMP_ASYSTEM_11
Heating cableHeating cable for pump AHEATING_CABLEPUMP_A
PumpBackup pump for system 11PUMP_BSYSTEM_11
You can post all assets in one request when you structure an asset hierarchy. 
POST /api/v1/projects/<project>/assets
Host: api.cognitedata.com
Request body:
{
  "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:
{
  "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.

​
Rate and concurrency limits

For Assets rate and concurrency limits, see API rate limits.
Last modified on April 23, 2026