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 workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.
Like Comments, Annotations are a means by which your team can communicate about the Assets 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.
Log in using an Authentication Key or email / password.
Returns an x-auth-token in the Response Headers.
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.
Generate a Refresh Token for the Organization.
Pass the x-auth-token from Step 1 in the Request Headers.
1234{‘x-auth-token’ : ‘Bearer ‘ + x_auth_token‘organizationUuid’ : ‘string’}Returns the Refresh Token as the Response Header x-auth-token.
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.
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 UUID’s.
12345{‘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 Asset you wish to add the Annotation to. View our guide of searching for Assets to see the different options available for this, otherwise you can use the below example to search for an Asset by name. Note: Assets in Draft status are not searchable via the API, they must be in the Live Internal or Live Public states.
The Request is structured as follows:
The Response is structured as follows:
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.
Creating an Annotation
With the Asset UUID in hand, you can make a request to the following endpoint to add an Annotation.
- 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 Workspace containing the Asset 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 Asset 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.
Retrieve Annotations for Assets
Retrieving Annotations for an Asset will require first that you obtain the UUID of the Asset in question. You can use the search example shown above or view the guide on searching for Assets.
With the Assets UUID in hand, you can call the following endpoint to retrieve Annotations:
For this endpoint, page 0 represents the first page of results. This will return a result similar to the following:
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:
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.