> ## 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.

# Labels

> Create and manage labels in Cognite Data Fusion (CDF).

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](/api-reference/concepts/20230101/relationships) 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`.

<AccordionGroup>
  <Accordion title="Example: create labels">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

<AccordionGroup>
  <Accordion title="Example: create an asset with labels">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    POST /api/v1/projects/publicdata/assets
    Content-Type: application/json

    {
      "items": [
        {
          "externalId": "MY_PUMP_ASSET",
          "labels": [
            { "externalId": "PUMP" },
            { "externalId": "rotating-equipment" }
          ]
        }
      ]
    }
    ```

    <Note>
      You can attach a maximum of 10 labels to each resource.
    </Note>
  </Accordion>
</AccordionGroup>

## 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.

<AccordionGroup>
  <Accordion title="Example: attach and remove labels">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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.
  </Accordion>
</AccordionGroup>

## Filter resources by labels

To filter assets by a label, reference the label through the `externalId` when you filter.

<AccordionGroup>
  <Accordion title="Example: filter assets by labels">
    To retrieve only assets that have the label `rotating-equipment`:

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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`:

    ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "filter": {
        "labels": {
          "containsAny": [
            { "externalId": "rotating-equipment" },
            { "externalId": "PUMP" }
          ]
        }
      }
    }
    ```

    To retrieve only assets that have the labels `rotating-equipment` **and** `pump`:

    ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "filter": {
        "labels": {
          "containsAll": [
            { "externalId": "rotating-equipment" },
            { "externalId": "PUMP" }
          ]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Delete labels

To delete a label, specify the `externalId` of the label to delete.

<AccordionGroup>
  <Accordion title="Example: delete a label">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    POST /api/v1/projects/publicdata/labels/delete
    Content-Type: application/json
    {
      "items": [
        {
          "externalId": "rotating-equipment"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>