VNTANA Logo - White
Book A Call

Resources

API – Annotations

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 here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.

Like Comments, Annotations are a means by which your team can communicate about the Product’s in your Organization, however unlike Comments these actually exist in the 3D viewer, in 3D space, allowing for direct correlation between the message of the Annotation and a part of the 3D model. 

As with all uses of the Admin API, you must first properly authenticate. View our guide on Authentication for a detailed look at the steps involved, otherwise you can use the below example to implement the steps.

  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 Clients / Folders and store the needed UUID.

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

    • This step can be skipped if the Client / Folder UUID is already stored locally.

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

    • Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.

      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.

Once authenticated, you will have to retrieve the UUID of the Product you wish to add the Annotation to. View our guide of searching for Products to see the different options available for this, otherwise you can use the below example to search for a Product by name.

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 Product name is quite unique, you’ll likely have to iterate over the results to match the name exactly.

Creating an Annotation

With the Product UUID in hand, you can make a request to the following endpoint to add an Annotation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Method: POST
Endpoint: /v1/annotations
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘attachments’ : [
‘blobId’ : ‘string’,
‘name’ : ‘string’,
‘productUuid’ : ‘string’
],
‘clientUuid’ : ‘string’,
‘dimensions’ : ‘{\’position\’: \’0.0m 0.0m 0.0m\’,\’normal\’: \’0.0m 0.0m 0.0m\’}’,
‘productUuid’ : ‘string’,
‘text’ : ‘The annotations message’
}
  • annotations: An attachment can be uploaded with the Annotation, allowing another user to download it. This can be an image representing how the model should look, or for example a json file containing information the other user may need.
    • blobId: The UUID of the attached file.
    • name: The name of the attached file.
    • productUuid: The UUID of the attachment itself (details including name, creation timestamp, and file ID, etc.). This is what would be used should you wish to search for the attachment via the API.
  • clientUuid: The UUID of the Client / Folder containing the Product you wish to create an annotation for.
  • dimensions: A stringified json object containing 3D position and normals as strings. It is very important that you escape the double quotes found within the parameter or the front-end won’t be able to parse the information correctly and will cause issues.
    • The sample above shows this exactly as it needs to be entered. With the exception of the first and last double quote (“), you must place a \ in front of each interior double quote.
  • productUuid: The UUID of the product for which the Annotation will be created.
  • text: The text content of the Annotation.
  • All are required, however for attachments you can simply pass an empty list ([ ]) if you have nothing to attach. It you do choose to pass an attachment you must first create it, you can view the full API documentation linked above to see how to upload an attachment through the API.

Note: For the dimensions parameter, every single or double quote found within the value itself must be escaped by the character ‘\’ as shown in the above example, otherwise the data won’t be able to be read.

A successful creation will simply return the uuid of the newly created Annotation.

1
2
3
4
5
6
{
“response”: {
“uuid”: “string”
},
“success”: true
}

Retrieve Annotations for Product

Retrieving Annotations for a Product will require first that you obtain the UUID of the Product in question. You can use the above Product search example or view the guide on searching for Products.

With the Product UUID in hand, you can call the following endpoint to retrieve Annotations:

1
2
3
4
5
6
7
8
Method: POST
Endpoint: /v1/annotations/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘page’ : 0,
‘size’ : 10,
‘productUuid’ : ‘string’
}

For this endpoint, page 0 represents the first page of results. This will return a result similar to the following:

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-30T06:10:55.346Z”,
“entityType”: “COMMENT”,
“entityUuid”: “string”,
“name”: “string”,
“type”: “PRODUCT”,
“updated”: “2022-06-30T06:10:55.346Z”,
“uuid”: “string”
}
],
“totalCount”: 0
},
“commentsCount”: 0,
“created”: “2022-06-30T06:10:55.346Z”,
“dimensions”: “string”,
“number”: 0,
“productUuid”: “string”,
“resolved”: true,
“text”: “string”,
“updated”: “2022-06-30T06:10:55.346Z”,
“userUuid”: “string”,
“uuid”: “string”
}
],
“nextNumber”: 0,
“totalCount”: 0
},
“mentions”: {
“grid”: [
{
“email”: “string”,
“fullName”: “string”,
“imageBlobId”: “string”,
“inOrganization”: true,
“uuid”: “string”
}
],
“totalCount”: 0
}
},
“success”: true
}

The Attachments uuid is found in the individual entries in the annotations grid, not the mentions grid.

Resolving Annotations

Annotations can be used to point out issues with the 3D model, or incorrect patterns in one portion of the asset. Additionally, Annotations are able to be ‘resolved’, meaning the issue or comment has been addressed and no further action is necessary. This allows you to keep a record of what has and hasn’t been handled without having to delete each Annotation.

The endpoint to handle this only requires the Annotations uuid, which can be retrieved using the above mentioned endpoint. With the uuid in hand, call the following endpoint with resolved set to true or false: 

1
2
3
4
5
6
7
Method: POST
Endpoint: /v1/annotations/resolve
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“resolved” : true,
“uuid” : “string”
}

If successful, it will only return the uuid of the now resolved Annotation.

Postman Collection

You can download the below Postman collection to test out each of these Annotation based interactions. The collection includes everything needed to run a chain of endpoints from authentication to Annotation creation and resolution. To run it as a collection, simply uncheck any Authentication endpoints you don’t need based on your user access (see our Authentication guide for a detailed explanation) as well as enter the Annotation parameters you wish to pass along such as message. 

To run the endpoints individually, make sure to activate the deactivated X-AUTH-TOKEN header for each endpoint, and ensure all the necessary parameters are entered in the body or query params of each. For more information on using Postman collections, see our guide.

Postman

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.
Learn More

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

OK