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.

Create a new tag

EndpointQuery ParametersPayload ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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

EndpointQuery ParametersPayload ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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