Skip to content

Tag API Reference Guide

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

Note

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

Endpoint

Method Path Purpose
POST /tag Create a new tag.

Query Parameters

None.

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 decription 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

Endpoint

Method Path Purpose
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. 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 decription 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

Endpoint

Method Path Purpose
POST /tag/refresh Refresh external tags.

Query Parameters

None.

Response Parameters

None.

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

Endpoint

Method Path Purpose
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

Endpoint

Method Path Purpose
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 decription 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

Endpoint

Method Path Purpose
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

Response Parameters

None.

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