Resources

API – Comments

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.

Another feature offered on the VNTANA Platform are Comments. Comments can be added to a number of different entities: Assets, Projects, Configurators, and Annotations. This feature allows team members to easily communicate, and by utilizing the Admin API you can automatically create Comments on an Asset upon the notification of a status change by a Webhook.

As with all Admin API processes you must first authenticate. View our Authentication guide for a detailed explanation of the steps involved, or use the below summary to authenticate.

  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.

Create a Comment

To create a comment, you must first determine the entity that the comment will be added to and retrieve its UUID. Below are examples of searching for entities, or view our guides on searching Assets, ProjectsConfigurators, or AnnotationsNote: In order to search for Assets and Projects they must be in either the Live Internal or Live Public status. Draft entities will not be returned.

The Request is structured as follows:

1
2
3
4
5
6
7
8
9
10
Method: POST
Endpoint: /v1/products/clients/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘page’ : 1,
‘size’ : 10,
‘clientUuids’ : [ ‘some-client-uuid’ ],
‘searchTerm’ : ‘string’,
‘name’ : ‘string’
}

The Response is structured as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“clientUuid”: “string”,
“clientSlug”: “some-client-slug”,
“name”: “string”,
“locations”: [],
“tags”: [],
“variantGroups”: [],
“status”: “LIVE”,
“conversionStatus”: “COMPLETED”,
“asset”: {
“generationRequestUuid”: “string”,
“thumbnailBlobId”: “string”,
“assetBlobId”: “string”,
“assetOriginalName”: “string”,
“materialBlobId”: null,
“conversionFormats”: [
“GLB”,
“USDZ”
],
“models”: [
{
“uuid”: “string”,
“conversionFormat”: “GLB”,
“modelBlobId”: “string”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null
},
{
“uuid”: “string”,
“conversionFormat”: “USDZ”,
“modelBlobId”: “string”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null
}
]
},
“created”: “2022-06-26T22:21:26.744”,
“attributes”: [],
“updated”: “2022-06-26T22:34:57.042706”,
“malwareProcessingStatus”: null
}
]
}
}

The searches are fuzzy, meaning they return results based on relevance. Unless every Asset name is quite unique, you’ll likely have to iterate over the results to match the name exactly.

The Request is structured as follows:

1
2
3
4
5
6
7
8
9
10
11
Endpoint: /v1/variant-groups/search
Method: POST
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘clientUuids’ : [
‘some-client-uuid’
],
‘page’ : 1,
‘size’ : 10,
‘searchTerm’ : ‘string’
}

The Response is structured as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
“success” : true,
“errors” : [],
“response” : {
“totalCount” : int,
“grid” : [
“uuid” : “string”,
“clientUuid” : “string”,
“clientSlug” : “some-client-slug”,
“name” : “string”,
“description” : “string”,
“tags” : [
{
“uuid” : “string”,
“name” : “string”
}
],
“productsUuids” : [
“some-product-uuid”, “another-product-uuid”
],
“status” : “DRAFT” or “LIVE”,
“created” : “timestamp”,
“updated” : “timestamp”
]
}
}

The Request is structured as follows:

1
2
3
4
5
{
“page”: 1,
“productUuid”: “string”,
“size”: 10
}

The Response is structured as follows

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
“response”: {
“annotations”: {
“grid”: [
{
“attachments”: {
“grid”: [
{
“blobId”: “string”,
“created”: “2022-06-30T05:23:23.741Z”,
“entityType”: “COMMENT”,
“entityUuid”: “string”,
“name”: “string”,
“type”: “PRODUCT”,
“updated”: “2022-06-30T05:23:23.741Z”,
“uuid”: “string”
}
],
“totalCount”: 0
},
“commentsCount”: 0,
“created”: “2022-06-30T05:23:23.741Z”,
“dimensions”: “string”,
“number”: 0,
“productUuid”: “string”,
“resolved”: true,
“text”: “string”,
“updated”: “2022-06-30T05:23:23.741Z”,
“userUuid”: “string”,
“uuid”: “string”
}
],
“nextNumber”: 0,
“totalCount”: 0
},
“mentions”: {
“grid”: [
{
“email”: “string”,
“fullName”: “string”,
“imageBlobId”: “string”,
“inOrganization”: true,
“uuid”: “string”
}
],
“totalCount”: 0
}
},
“success”: true
}

Using the Asset example, with the Asset UUID in hand, you can call the following endpoint, setting entityType to ‘PRODUCT’:

1
2
3
4
Method: POST
URL: /v1/comments/create
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘message’, ‘entityUuid’, ‘entityType’

The message parameter is of course the text of the comment itself. This will return the uuid of the comment in the Response body which is needed to edit or delete the comment.

Retrieving Comments

To retrieve the comments of an entity such as Assets, you will need to know the entityUuid. Using an Asset as an example, use the above Asset Search example to retrieve this UUID, then use the following endpoint to pull its comments:

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

This will return the following Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
“response”: {
“comments”: {
“grid”: [
{
“attachments”: {
“grid”: [
{
“blobId”: “string”,
“created”: “2022-06-30T05:35:01.132Z”,
“entityType”: “COMMENT”,
“entityUuid”: “string”,
“name”: “string”,
“type”: “PRODUCT”,
“updated”: “2022-06-30T05:35:01.132Z”,
“uuid”: “string”
}
],
“totalCount”: 0
},
“created”: “2022-06-30T05:35:01.132Z”,
“entityType”: “ANNOTATION”,
“entityUuid”: “string”,
“message”: “string”,
“updated”: “2022-06-30T05:35:01.132Z”,
“userUuid”: “string”,
“uuid”: “string”
}
],
“totalCount”: 0
},
“mentions”: {
“grid”: [
{
“email”: “string”,
“fullName”: “string”,
“imageBlobId”: “string”,
“inOrganization”: true,
“uuid”: “string”
}
],
“totalCount”: 0
}
},
“success”: true
}

This will return information on both the Comment itself and the entity it is attached to.

Postman Collections

You can test the above endpoints with the following Postman collection. This collection contains everything you need to create or retrieve comments, from authentication to creation. To run the collection as a whole, you will need to deselect the endpoints you do not need or want to run, and ensure the global variables are set in the collections Pre-request Script.

If you would like to run the endpoints individually you must re-enable the X-AUTH-TOKEN header for all endpoints except the login endpoints, and ensure each endpoint has the necessary body and query parameters.

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.