Resources

API – Creating Tags and Tag Groups

API Base URL: https://api-platform.vntana.com

For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation hereNote: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.

Creating a Tag

Tags are a great way to both add insightful metadata to Assets as well as create a means of filtering results when searching for Assets. Tags are created within and are unique to a Workspace. This means the Tag “Woven” can only exist once in a Workspace, but can be applied to every Asset within if desired. This also means, however, that the Tag “Woven” must be created again in every Workspace that it is needed, as it cannot be applied to Assets in another Workspace.

In addition to Asset Tags, Configurators and Projects can have Tags applied to them. These Tags share the Workspace Tag pool with Assets, meaning the Tag “Woven” can be applied to an Asset, a Project, and a Configurator. However, a Tag applied to a Configurator or Project doesn’t automatically get added to the Assets associated with them.

As with all endpoints in the Admin API, you must first complete the appropriate level of authentication for your account and generate a Refresh Token (Authentication guide). 

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

  2. Retrieve a list of Organizations and store the needed Organization’s UUID.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      { ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token }
    • This step can be skipped if the Organization UUID is already stored locally.

  3. Generate a Refresh Token for the Organization.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      2
      3
      4
      {
      ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
      ‘organizationUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

  4. Retrieve a list of Workspaces and store the needed UUID.

    • Pass the x-auth-token in the Request Headers.

    • This step can be skipped if the Workspace UUID is already stored locally.

  5. Generate a Refresh Token for the Workspace (Organization Admin / Owner users must skip this step).

    • Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Workspace UUIDs.

      1
      2
      3
      4
      5
      {
      ‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
      ‘organizationUuid’ : ‘string’,
      ‘clientUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

To create a Tag, you should first check to verify the Tag doesn’t already exist within the Workspace. You can skip this and just move on if the request returns the Error message that the Tag already exists, however unless you are simply creating a batch of Tags and do not need the Tag UUID right away, it would be best to search the Tags first to retrieve the UUID of already created Tags for immediate use.

1
2
3
4
5
6
7
8
9
Method: POST
Endpoint: /v1/tags/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“clientUuid”: “string”,
“page”: 1,
“searchTerm”: “string”,
“size”: 10
}

Once you have confirmed the Tag you wish to create doesn’t already exist, you can simply make the following Request:

1
2
3
4
5
6
7
8
Method: POST
Endpoint: /v1/tags/create
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘clientUuid’ : ‘some-client-uuid’,
‘name’ : ‘Some Tag’,
‘tagGroupUuid’ : ‘some-tag-group-uuid’
}

Only clientUuid and name are required for the request body. A successful request will return the newly created Tags UUID in the Response Body and can then be passed in the tequest body of an Asset Creation request, Configurator Creation request, Project Creation request, or simply stored locally to avoid having to make an API call to check on Tags and retrieve their UUID’s.

Tag Groups

Another Tag related feature are Tag Groups. Like Tags these are Workspace specific and act as a means of organizing your Tags. You can create a Tag Group and then create Tags related to this group, allowing you to then make an API call to retrieve the Tag Group with all Tags names and UUID’s returned, instead of needing to search for each Tag individually. Note: Tag Groups do not overwrite the restriction of each Tag existing once in a Workspace, the same Tag cannot be created or applied to multiple Tag Groups.

To retrieve Tag Groups, use the following endpoint:

1
2
3
4
5
Method: GET
Endpoint: /v1/tag-groups/clients/client-uuid
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘page’, ‘size’
Example: https://api-platform.vntana.com/v1/tag-groups/clients/client-uuid?page=0&size=10

Please note, for this endpoint, the first page is actually 0 not 1, and page and size are required.

A sample response from a successful Tag Group search:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “some-tag-group-uuid”,
“name”: “UNASSIGNED”,
“tags”: [
{
“uuid”: “tag-uuid-1”,
“name”: “Some Tag 1”
},
{
“uuid”: “tag-uuid-2”,
“name”: “Some Tag 2”
}
]
}
]
}
}

To create a Tag Group, use the following endpoint:

1
2
3
4
5
6
7
Method: POST
Endpoint: /v1/tag-groups/create
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘clientUuid’ : ‘some-uuid’,
‘name’ : ‘string’
}

Tag Groups are not required, any Tag created without specifying a Tag Group will be placed in the UNASSIGNED Tag Group which is the default of every Workspace.

Postman Collection

To test these processes, we’ve included two Postman collections, one to create a Tag and one to create a Tag Group. For both, you will need to set the various global variables in the Pre-request Script of the collection itself, and each can be run as either a full collection (simply select which endpoints you wish to run) or as individual endpoints. To run the endpoints individually you will have to activate the deactivated headers and make sure the necessary data is filled in for each endpoint. Additionally, for the Tag Group collection, the actual Tag Group creation endpoint will fail if a Tag Group already exists, so don’t be alarmed if that single endpoint fails. You can view our general guide on using Postman collections here.

Create Tags Collection

Create Tag Group Collection

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.