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

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.

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

/tag/{modelType}/{modelId}

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}

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

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

Last updated

Copyright © 2014-2024 Immuta Inc. All rights reserved.