# Manage Tags

This page describes the `tag` endpoint, which can be used to manage tags on data sources, columns, and projects.

{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}

## Tagging workflow

1. [Create or update a tag](#create-or-update-a-tag).
2. [Search across all tags](#search-across-all-tags).
3. [Refresh external tags.](#refresh-external-tags)
4. [Add tags to a data source, column, or project.](#add-tags-to-a-data-source-column-or-project)
5. [Delete tags](#delete-tags).

## Create or update a tag

<mark style="color:green;">`POST`</mark> `/tag`

#### Payload parameters

| Attribute                   | Description                                                                                                                                                                                                                                                                                                                                                                          | Required                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| **tags**                    | `array[string]` A list of tags to create or update.                                                                                                                                                                                                                                                                                                                                  | **Yes**                                                                                                   |
| tags.**name**               | <p><code>string</code> The fully-qualified tag name. The name of the parent tag and its child tags are delimited by a <code>.</code>. See the <a href="#payload-example">payload example below</a>.<br><br>If you are updating an existing parent tag with new child tags, the parent value for this attribute should be the same as the value of <strong>rootTag.name</strong>.</p> | **Yes**                                                                                                   |
| tags.**id**                 | `integer` The unique identifier of the tag you want to update.                                                                                                                                                                                                                                                                                                                       | Required for updating an **existing tag**. This attribute should not be included when creating a new tag. |
| **rootTag**                 | `object` When provided, allows the requestor to update an existing parent tag.                                                                                                                                                                                                                                                                                                       | No                                                                                                        |
| rootTag.**name**            | `string` The name of the parent tag to update.                                                                                                                                                                                                                                                                                                                                       | Required if **rootTag** is provided.                                                                      |
| rootTag.**source**          | `string` The source from which the parent tag was created. Acceptable value is `curated`.                                                                                                                                                                                                                                                                                            | No                                                                                                        |
| rootTag.**deleteHierarchy** | <p><code>boolean</code> When <code>true</code>, all of the existing child tags will be deleted and replaced with the new child tags you include in the <strong>tags</strong> array.<br><br>If this value is <code>false</code>, the existing child tags will remain.</p>                                                                                                             | No                                                                                                        |

#### Response parameters

| Attribute         | Description                                                                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **id**            | `integer` The tag ID.                                                                                                                                        |
| **name**          | `string` The fully-qualified tag name.                                                                                                                       |
| **source**        | `string` The system the tag was created by. When `curated`, the tag was created in Immuta.                                                                   |
| **createdBy**     | `integer` The profile ID of the creator.                                                                                                                     |
| **createdAt**     | `timestamp` The date and time of the tag creation.                                                                                                           |
| **updatedAt**     | `timestamp` The date and time of the tag update.                                                                                                             |
| **displayName**   | `string` The tag name that will display in the console.                                                                                                      |
| **protected**     | `boolean` When `true`, indicates the tag cannot be updated. Tags created by Immuta will always be protected. This value will be `false` for tags you create. |
| **systemCreated** | `boolean` When you create a tag, this value will be `false`, which indicates that this tag was not created by Immuta.                                        |

### Request example

The following request creates a new tag.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example_payload.json \
    https://your-immuta-url.com/tag
```

#### Payload example

{% tabs %}
{% tab title="New parent tag example" %}
The payload below creates the parent tag `Address` with 3 child tags: `email`, `work`, `home`.

```json
{
  "tags": [{
    "name": "Address.email"
  }, {
    "name": "Address.work"
  }, {
    "name": "Address.home"
  }]
}
```

{% endtab %}

{% tab title="Update a parent tag example" %}
The payload below changes the names of the existing child tags of the `Address` parent tag to `state`, `city`, `zip`.

```json
{
  "rootTag": {
    "name": "Address",
    "deleteHierarchy": false
  },
  "tags": [{
    "id": 129,
    "name": "Address.state"
  }, {
    "id": 130,
    "name": "Address.city"
  }, {
    "id": 131,
    "name": "Address.zip"
  }]
}
```

{% endtab %}
{% endtabs %}

### Response example

{% tabs %}
{% tab title="New parent tag example" %}

```json
[{
  "id": 129,
  "name": "Address.email",
  "color": null,
  "description": null,
  "source": "curated",
  "deleted": false,
  "systemCreated": false,
  "createdBy": 2,
  "createdAt": "2021-10-08T20:53:22.946Z",
  "updatedAt": "2021-10-08T20:53:22.946Z"
}, {
  "id": 130,
  "name": "Address.work",
  "color": null,
  "description": null,
  "source": "curated",
  "deleted": false,
  "systemCreated": false,
  "createdBy": 2,
  "createdAt": "2021-10-08T20:53:22.946Z",
  "updatedAt": "2021-10-08T20:53:22.946Z"
}, {
  "id": 131,
  "name": "Address.home",
  "color": null,
  "description": null,
  "source": "curated",
  "deleted": false,
  "systemCreated": false,
  "createdBy": 2,
  "createdAt": "2021-10-08T20:53:22.946Z",
  "updatedAt": "2021-10-08T20:53:22.946Z"
}]
```

{% endtab %}

{% tab title="Update an existing parent tag example" %}

```json
[{
    "id": 129,
    "name": "Address.state",
    "source": "curated",
    "deleted": false,
    "systemCreated": false,
    "createdBy": 2,
    "createdAt": "2025-08-25T19:23:06.709Z",
    "updatedAt": "2025-08-25T19:23:54.860Z",
    "color": null,
    "description": null,
    "displayName": "state",
    "protected": false
  },
  {
    "id": 130,
    "name": "Address.city",
    "source": "curated",
    "deleted": false,
    "systemCreated": false,
    "createdBy": 2,
    "createdAt": "2025-08-25T19:23:06.709Z",
    "updatedAt": "2025-08-25T19:23:54.863Z",
    "color": null,
    "description": null,
    "displayName": "city",
    "protected": false
  },
  {
    "id": 131,
    "name": "Address.zip",
    "source": "curated",
    "deleted": false,
    "systemCreated": false,
    "createdBy": 2,
    "createdAt": "2025-08-25T19:23:06.709Z",
    "updatedAt": "2025-08-25T19:23:54.867Z",
    "color": null,
    "description": null,
    "displayName": "zip",
    "protected": false
  }
]
```

{% endtab %}
{% endtabs %}

## Search across all tags

<mark style="color:green;">`GET`</mark> `/tag`

#### Query parameters

| Attribute                | Description                                                                                                                                    | Required |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **searchText**           | `string` A string used to filter returned tags. The query is executed with a wildcard prefix and suffix.                                       | No       |
| **source**               | `string` Filter tags by the source that created them.                                                                                          | No       |
| **excludedSource**       | `string` Only return tags that do not have this source.                                                                                        | No       |
| **includeAllSystemTags** | `boolean` If `true`, includes all system tags even if they have been deleted. Otherwise, set to `false` to filter out all system-created tags. | No       |
| **excludedHierarchies**  | `array[string]` A string used to filter returned tags. The query is executed with a wildcard prefix and suffix.                                | No       |
| **limit**                | `integer` The maximum number of search results that will be returned.                                                                          | No       |

#### Response parameters

| Attribute         | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **id**            | `integer` The tag ID.                                                                                                             |
| **name**          | `string` The fully-qualified tag name.                                                                                            |
| **color**         | `string` An uneditable tag field.                                                                                                 |
| **description**   | `string` An uneditable tag field that appears as a tag description in the UI. Built-in tags come with descriptions pre-populated. |
| **source**        | `string` The system the tag was created by. When `curated`, the tag was created in Immuta.                                        |
| **deleted**       | `boolean` If `true`, the tag has been deleted.                                                                                    |
| **systemCreated** | `boolean` When `true`, the tag was created by Immuta.                                                                             |

### Request example

The following request searches all tags.

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/tag
```

### Response example

```json
[
  {
    "id": 114,
    "name": "DataProperties.Cross-Sectional",
    "color": null,
    "description": null,
    "source": "curated",
    "deleted": false,
    "systemCreated": true
  },
  {
    "id": 2,
    "name": "Discovered.Country.Argentina",
    "color": null,
    "description": null,
    "source": "curated",
    "deleted": false,
    "systemCreated": true
  },
  {
    "id": 9,
    "name": "Discovered.Country.Australia",
    "color": null,
    "description": null,
    "source": "curated",
    "deleted": false,
    "systemCreated": true
  }
]
```

## Refresh external tags

<mark style="color:green;">`POST`</mark> `/tag/refresh`

### Request example

The following request refreshes external tags.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/tag/refresh
```

## Add tags to a data source, column, or project

<mark style="color:green;">`POST`</mark> `/tag/{modelType}/{modelId}`

No tags will be processed if any invalid tags are found in the payload.

### Query parameters

| Attribute     | Description                                                                                                                                                                           | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **modelType** | `string` The Immuta component to add the tag to: `datasource`, `column`, or `project`.                                                                                                | **Yes**  |
| **modelId**   | `string` The ID of the column, data source, or project. *Note: The `modelId` for a column is the data source ID followed by followed by `_<column name>`. For example, `49_address`.* | **Yes**  |

### Payload parameters

No tags will be processed if any invalid tags are found in the payload.

| Attribute         | Description                                                                                          | Required |
| ----------------- | ---------------------------------------------------------------------------------------------------- | -------- |
| **name**          | `string` The fully-qualified name of the tag.                                                        | **Yes**  |
| **id**            | `integer` The tag ID.                                                                                | No       |
| **displayName**   | `string` The tag's name that is displayed in the console.                                            | No       |
| **source**        | `string` The name of the system that created the tag. When `curated`, the tag was created in Immuta. | No       |
| **systemCreated** | `boolean` When `true`, the tag was created by Immuta.                                                | No       |
| **addedBy**       | `integer` The profile ID of the user who added the tag to the data source, column, or project.       | No       |
| **deleted**       | `boolean` When `true`, the tag has been deleted.                                                     | No       |
| **hasLeafNodes**  | `boolean` When `true`, parent tags exist within the tag hierarchy that have no child tags.           | No       |
| **createdBy**     | `integer` The profile ID of the user who created the tag.                                            | No       |
| **createdAt**     | `date` When the tag was created.                                                                     | No       |
| **updatedAt**     | `date` When the tag was last updated.                                                                | No       |

### Response parameters

| Attribute   | Description                                                                                |
| ----------- | ------------------------------------------------------------------------------------------ |
| **name**    | `string` The fully-qualified name of the tag.                                              |
| **source**  | `string` The system the tag was created by. When `curated`, the tag was created in Immuta. |
| **addedBy** | `integer` The profile ID of the user who added the tag.                                    |
| **deleted** | `boolean` When `true`, the tag has been deleted.                                           |

### Add tags to a data source example

**Request example**

The following request adds a tag to the data source with the data source ID `22`.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example_payload.json \
    https://your-immuta-url.com/tag/datasource/22
```

**Request payload example**

```json
[{
  "name": "Discovered.Passport",
  "source": "curated"
}]
```

**Response example**

```json
[{
  "name": "Discovered.Passport",
  "source": "curated",
  "addedBy": 2,
  "deleted": false
}]
```

### Add tags to a project

**Request example**

The following request adds a tag to the project with the project ID `2`.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example_payload.json \
    https://your-immuta-url.com/tag/project/2
```

**Request payload example**

```json
[{
  "name": "Confidential",
  "source": "curated"
}]
```

**Response example**

```json
[{
  "name": "Confidential",
  "source": "curated",
  "context": "manual",
  "addedBy": 2,
  "deleted": false
}]
```

### Add tags to a data source column

**Request example**

The following request adds a tag to the `countrycode` column of the data source with the data source ID `6`.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example_payload.json \
    https://your-immuta-url.com/tag/column/6_countrycode
```

**Request payload example**

```json
[{
  "name": "Discovered.Passport",
  "source": "curated"
}]
```

**Response example**

```json
[{
  "name":"Discovered.Passport",
  "source":"curated",
  "context":"manual",
  "addedBy":2,
  "deleted":false
}]
```

## Delete tags

| Endpoint                           | Purpose                                                                                                  |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `/tag/{tag}`                       | [Delete a tag](#delete-a-tag).                                                                           |
| `/tag/{modelType}/{modelId}/{tag}` | [Remove tags from a data source, column, or project](#remove-tags-from-a-data-source-column-or-project). |

### Delete a tag

<mark style="color:green;">`DELETE`</mark> `/tag/{tag}`

#### Query parameters

| Attribute           | Description                                                  | Required |
| ------------------- | ------------------------------------------------------------ | -------- |
| **tag**             | `string` The fully-qualified name of the tag.                | **Yes**  |
| **deleteHierarchy** | `boolean` If `true` it will delete the entire tag hierarchy. | No       |

#### Response parameters

| Attribute         | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **id**            | `integer` The tag ID.                                                                                                             |
| **name**          | `string` The fully-qualified tag name.                                                                                            |
| **color**         | `string` An uneditable tag field.                                                                                                 |
| **description**   | `string` An uneditable tag field that appears as a tag description in the UI. Built-in tags come with descriptions pre-populated. |
| **source**        | `string` The system the tag was created by. When `curated`, the tag was created in Immuta.                                        |
| **deleted**       | `boolean` If `true`, the tag has been deleted.                                                                                    |
| **systemCreated** | `boolean` When `true`, the tag was created by Immuta.                                                                             |
| **createdBy**     | `string` The profile ID of the creator.                                                                                           |
| **createdAt**     | `timestamp` The date and time of the tag creation.                                                                                |
| **updatedAt**     | `timestamp` The date and time of the tag update.                                                                                  |

#### Request example

The following request deletes a tag.

```shell
curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/tag/DataProperties.Cross-Sectional
```

#### Response example

```json
[
  {
    "id": 114,
    "name": "DataProperties.Cross-Sectional",
    "color": null,
    "description": null,
    "source": "curated",
    "deleted": true,
    "systemCreated": true,
    "createdBy": null,
    "createdAt": "2021-06-24T15:08:53.119Z",
    "updatedAt": "2021-09-27T19:00:38.828Z"
  }
]
```

### Remove tags from a data source, column, or project

<mark style="color:green;">`DELETE`</mark> `/tag/{modelType}/{modelId}/{tag}`

#### Query parameters

| Attribute     | Description                                                                                                                                                                           | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **tag**       | `string` The name of the tag.                                                                                                                                                         | **Yes**  |
| **modelType** | `string` The Immuta component to remove the tag from: `datasource`, `column`, or `project`.                                                                                           | **Yes**  |
| **modelId**   | `string` The ID of the column, data source, or project. *Note: The `modelId` for a column is the data source ID followed by followed by `_<column name>`. For example, `49_address`.* | **Yes**  |

#### Request example

The following request deletes a tag.

```shell
curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/tag/datasource/523/Discovered.Country.Canada
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/2024.2/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/tagging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.