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 a new tag.

2. Search across all tags.

3. Update tags.

4. Delete tags.

Create a new tag

POST /tag

Create a new tag.

Payload parameters

Attribute	Description	Required
name	string The name of the tag.	Yes
id	integer The tag ID.	No
rootTag	array When provided, indicates the name of the root (or parent) tag that the child tag will fall under. If a child tag is added, the deleteHierarchy value will be true.	No

Response parameters

Attribute	Description
id	integer The tag ID.
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.
name	string The tag name.
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 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

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

Response 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.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"
}, {
  "id": 131,
  "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"
}]

Search across all tags

GET /tag

Search across all tags.

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 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
  },
]

Update tags

Endpoint	Purpose
/tag/refresh	Refresh external tags.
/tag/{modelType}/{modelId}	Add tags to a particular model.

Refresh external tags

POST /tag/refresh

Refresh external tags.

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 particular model

POST /tag/{modelType}/{modelId}

Add tags to a particular model. 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 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 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

Request example

The following request adds tags 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 tags 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 tags 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}	Delete tags from a particular model.

Delete a tag

DELETE /tag/{tag}

Delete a tag.

Query parameters

Attribute	Description	Required
tag	string The name of the tag.	Yes
deleteHierarchy	boolean If true it will delete the entire hierarchy.	No

Response parameters

Attribute	Description
id	integer The tag ID.
name	string The 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"
  }
]

Delete tags from a particular model

DELETE /tag/{modelType}/{modelId}/{tag}

Delete tags from a particular model.

Query parameters

Attribute	Description	Required
tag	string The name of the tag.	Yes
modelType	string The model type.	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