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.

With labels you can create a predefined set of managed terms that you can use to annotate and group assets, files, and relationships. You can organize labels in a way that makes sense in your business and use them to make it easier to find what you want. For example, you can create a label called pump and apply it to all asset resources that represent pumps, and then filter assets to see only pumps. You can also use labels to define and manage the available types for relationship resources. For example, you can define labels like these and use them as relationship types:
  • flowsTo - to describe the flow between assets.
  • belongsTo - to describe that a file resource belongs to a particular asset resource.
  • isParentOf - to build a hierarchy of assets.
  • implements - to describe that a physical item implements a functional asset at a specific point in time.
Each asset/file can have up to ten labels connected to it. You can filter assets/files by their labels to find a group of assets/files.

​
Create a label

To create a label, give it an ID and a name. The label ID must be an externalId. 
POST /api/v1/projects/publicdata/labels
Content-Type: application/json

{
  "items": [
    {
      "externalId": "rotating-equipment",
      "name": "Rotating equipment",
      "description": "Pumps, compressors, turbines"
    },
    {
      "externalId": "PUMP",
      "name": "Pump",
      "description": "Pumps"
    }
  ]
}

​
Attach a label when creating a resource

To attach a label when you create a resource, reference the labels through the externalId of the label. 
POST /api/v1/projects/publicdata/assets
Content-Type: application/json

{
  "items": [
    {
      "externalId": "MY_PUMP_ASSET",
      "labels": [
        { "externalId": "PUMP" },
        { "externalId": "rotating-equipment" }
      ]
    }
  ]
}
You can attach a maximum of 10 labels to each resource.

​
Attach or remove labels on an existing resource

To attach or remove labels to an existing resource, reference the labels through the externalId of the label when you update the resource. 
POST /api/v1/projects/publicdata/assets/update
Content-Type: application/json

{
  "items": [
    {
      "update": {
        "labels": {
          "add": [ { "externalId": "PUMP" } ],
          "remove": [ { "externalId": "rotating-equipment" } ]
        }
      },
      "externalId": "MY_PUMP_ASSET"
    }
  ]
}
The API ignores the request if you try to attach a label that’s already attached to the resource.

​
Filter resources by labels

To filter assets by a label, reference the label through the externalId when you filter.
To retrieve only assets that have the label rotating-equipment:
POST /api/v1/projects/publicdata/assets/list
Content-Type: application/json

{
  "filter": {
    "labels": {
      "containsAny": [{ "externalId": "rotating-equipment" }]
    }
  }
}
To retrieve only assets that have the label rotating-equipment or pump:
{
  "filter": {
    "labels": {
      "containsAny": [
        { "externalId": "rotating-equipment" },
        { "externalId": "PUMP" }
      ]
    }
  }
}
To retrieve only assets that have the labels rotating-equipment and pump:
{
  "filter": {
    "labels": {
      "containsAll": [
        { "externalId": "rotating-equipment" },
        { "externalId": "PUMP" }
      ]
    }
  }
}

​
Delete labels

To delete a label, specify the externalId of the label to delete. 
POST /api/v1/projects/publicdata/labels/delete
Content-Type: application/json
{
  "items": [
    {
      "externalId": "rotating-equipment"
    }
  ]
}
Last modified on April 23, 2026