Manage Tags

Tag API reference guide

This page describes the tag endpoint. When implemented, this standard REST interface can tag new data sources automatically.

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Tagging workflow

1. Create or update a tag.

2. Search across all tags.

3. Refresh external tags.

4. Add tags to a data source, column, or project.

5. Delete tags.

Create or update a tag

POST /tag

Payload parameters

Attribute	Description	Required
tags	array[string] A list of tags to create or update.	Yes
tags.name	string The fully-qualified tag name. The name of the parent tag and its child tags are delimited by a .. See the payload example below. 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 rootTag.name.	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	boolean When true, all of the existing child tags will be deleted and replaced with the new child tags you include in the tags array. If this value is false, the existing child tags will remain.	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.

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

Payload example

New parent tag example

The payload below creates the parent tag Address with 3 child tags: email, work, home.

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

Update a parent tag example

The payload below deletes the existing child tags from the Address parent tag and replaces them with the following child tags: state, city, zip.

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

Response example

New parent tag example

[{
  "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"
}]

Update an existing parent tag example

[{
    "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",
    "dataProductName": null,
    "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",
    "dataProductName": null,
    "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",
    "dataProductName": null,
    "protected": false
  }
]

Search across all tags

GET /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.

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

Response example

[
  {
    "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

POST /tag/refresh

Request example

The following request refreshes external tags.

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

POST /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 _OBJECTID (For example, 49_OBJECTID).	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.

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

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

Response example

[{
  "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.

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

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

Response example

[{
  "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.

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

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

Response example

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

Delete tags

Endpoint	Purpose
/tag/{tag}	Delete a tag.
/tag/{modelType}/{modelId}/{tag}	Remove tags from a data source, column, or project.

Delete a tag

DELETE /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.

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

Response example

[
  {
    "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

DELETE /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 _OBJECTID (For example, 49_OBJECTID).	Yes

Request example

The following request deletes a tag.

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