Tag API

Audience: System Administrators

Content Summary: 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.
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 od 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 Request Example

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

Response Example

[{
  "id": 129,
  "name": "Address.email",
  "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",
  "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",
  "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.
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",
    "source": "curated",
    "deleted": false,
    "systemCreated": true
  },
  {
    "id": 2,
    "name": "Discovered.Country.Argentina",
    "source": "curated",
    "deleted": false,
    "systemCreated": true
  },
  {
    "id": 9,
    "name": "Discovered.Country.Australia",
    "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.

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

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.PII",
  "source": "curated"
}]

Response Example

[{
  "name": "Discovered.PII",
  "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.PII",
  "source": "curated"
}]

Response Example

[{
  "name":"Discovered.PII",
  "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.
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 od 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",
    "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