Resources

Rest API Documentation V1.2

Rest API Quick Start Guide

This guide will give you a brief overview of how to use the VNTANA Admin API in order to login to our Platform, authenticate your account, and retrieve your organizations, clients, products, and any additional information about your products, such as tags and locations. For a more comprehensive overview of our API, please check out our detailed API Documentation here. We also have a public API that you can use to access your published products and hotspots. Documentation for the public API can be found here.

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

Login to the VNTANA Platform

  • Use the following endpoint to authenticate

Method: POST
Endpoint: /v1/auth/login
Sample Request Body: { “email”: “youremail@address.com”, “password”: “YourPassword1” }

  • On successful authentication, a temporary user authentication token, X-AUTH-TOKEN, will be returned in the Response Headers.

Retrieve your Organizations List

  • After authentication, you can retrieve the list of your Organizations using the X-AUTH-TOKEN Response Header from Step 1.

Method: GET
Endpoint: /v1/organizations
Headers: { “x-auth-token”: “Bearer ” + token }

  • The token is the X-AUTH-TOKEN value retrieved after logging in. Don’t forget to add “Bearer ” before your token value.
  • The response has the list of all the Organizations in your Platform account, including important details such as the name, role, slug, and uuid of each Organization.

Authenticating a Specific Organization (Retrieve the Refresh Token)

  • In order to authenticate a specific Organization to see the Clients and Products for that Organization, you must retrieve the Refresh Token, which is an Organization-specific token.
  • Pass the X-AUTH-TOKEN, as well as the UUID of the Organization you would like to view, as headers in the following endpoint:

Method: POST
Endpoint: /v1/auth/refresh-token
Headers: { “x-auth-token”: “Bearer ” + token, “organizationUuid”: uuid }

  • The token is still the same X-AUTH-TOKEN retrieved after successfully logging in, and the Organization UUID can be found from the list of Organizations returned in Step 2.
  • On successful authentication of the selected Organization, you will receive another X-AUTH-TOKEN Response Header. This is the Refresh Token for this Organization. Please keep in mind that the X-AUTH-TOKEN from Step 1 is different from the one described in this step (Step 3).
  • You can now access your Clients and Products for this Organization!

Retrieve Clients List for Selected Organization

  • Pass the Refresh Token retrieved from the previous step (Step 3) to the following endpoint in order to get your list of Clients for the selected Organization:

Method: GET
Endpoint: /v1/clients/client-organizations
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • A successful response will return the list of Clients for the selected Organization, as well as the name, role, slug, uuid, and other details for each Client.

Retrieve Products for Selected Client

  • In order to view the Products for a single Client, use the following endpoint:

Method: POST
Endpoint: /v1/products/clients/{clientUuid}/search
Sample Request Body: { “page”: 1, “searchTerm”: “string”, “size”: 10, “status”: “LIVE” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The list of Products retrieved can be filtered in a number of ways, including by Search Term, Tags, Locations, and Conversion Statuses. Please reference the linked full API Documentation above to see the different parameters accepted in the Request Body for this endpoint.
  • The “x-auth-token” header here also requires the Refresh Token (Organization-specific token) from Step 3.

Retrieve Locations

  • Use the following endpoint to get the list of Locations created under a specific Client:

Method: POST
Endpoint: /v1/locations/search
Sample Request Body: { “clientUuid”: clientUuid, “page”: 1, “size”: 5, “searchTerm”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The UUID for the selected Client must be passed in the request body.
  • Locations can be filtered by page, size, search term, and date. Please see the full API Documentation for a complete list of search filters.
  • The Refresh Token from Step 3 must also be passed as an “x-auth-token” header.

Retrieve Tags

  • Use the following endpoint to get the list of Tags created under a specific Client:

Method: POST
Endpoint: /v1/tags/search
Sample Request Body: { “clientUuid”: clientUuid, “page”: 1, “size”: 12, “searchTerm”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The UUID for the selected Client must be passed in the request body.

  • Tags can be filtered by page, size, and search term.

  • The Refresh Token from Step 3 must also be passed as an “x-auth-token” header.

Additional Notes

  • In order to authenticate another Organization, the Refresh Token for that Organization must be retrieved (repeat Step 3). Simply pass the temporary user authentication token from Step 1, as well as the UUID of the Organization you wish to view (retrieved from Step 2), into the Refresh Token endpoint (Step 3). On success, you will be able to see the Refresh Token (Organization-specific token) for the Organization you have selected to view.

  • Once you have the new Refresh Token, you can repeat Steps 4-7 in order to retrieve the Clients, Products, Locations, and Tags for that Organization.

Starting from version 1.2 of the VNTANA Admin API, you can now perform actions related to Annotations and Comments. Annotations allow you to leave pins directly on the 3D model with text notes for yourself or your team to see. With Comments, you can provide feedback or add notes for the entire Product from the Product Details Page. Below, you can find a few examples on how to use the API to create, edit, or delete Annotations and Comments.

Annotations

Create an Annotation

  • Use the following endpoint to create an Annotation:

Method: POST
Endpoint: /v1/annotations
Sample Request Body: {
“dimensions”: “{“position”: “0.0017966393878431288m 0.01154611014484365m 0.002267831995077924m”,”normal”: “0.4475415981843541m 0.8250387565067864m 0.3449892290439372m”}”,
“productUuid”: productUuid,
“text”: “The color of this fabric should be blue, not green.”
}
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • dimensions is a JSON string, which consists of the position and normal of the Annotation pin. Both values are necessary to place the pin in the correct X, Y, Z coordinates of the 3D model.

  • The productUuid is the ID of the product to which you want to add Annotations. This can be found on the Product Details Page.

  • text is a required string with any information you want to add to the Annotation.

  • On successful creation of the Annotation, the uuid of the Annotation will be returned in the response body. You will need the uuid of the Annotation if you want to delete or edit it.

Edit an Annotation

  • After you have created an Annotation, you can always edit its position or text:

Method: PUT
Endpoint: /v1/annotations
Sample Request Body: {
“dimensions”: “{“position”: “0.0017966393878431288m 0.01154611014484365m 0.002267831995077924m”,”normal”: “0.4475415981843541m 0.8250387565067864m 0.3449892290439372m”}”,
“text”: “string”,
“uuid”: annotationUuid
}
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • Note: The uuid in the Request Body is the uuid of the annotation, not the product.

Retrieve the Annotations for a Product

  • In order to see all of the Annotations for a product, you can use this endpoint:

Method: POST
Endpoint: /v1/annotations/search
Sample Request Body: { “page”: 0, “productUuid”: productUuid, “size”: 1000 }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The Page and Size can be adjusted to only retrieve a subset of the total list of Annotations.

Reply to an Annotation

  • You can also reply to any existing Annotations via the API:

Method: POST
Endpoint: /v1/comments
Sample Request Body: { “entityType”: “ANNOTATION”, “entityUuid”: annotationUuid, “message”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • Note: Replying to Annotations uses the same logic as Comments (hence the change in the entity type in the endpoint). The entityType in the Request Body specifies where the Comment is to be added. Here, the entityType is “ANNOTATION,” since we are adding a response to an Annotation. In the next section, you will see an example of Comments being added to a Product.

Comments

Create a Comment

  • In addition to adding comment responses to Annotations, you can also add Comments to your Products, which appear at the bottom of the Product Details Page:

Method: POST
Endpoint: /v1/comments
Sample Request Body: { “entityType”: “PRODUCT”, “entityUuid”: productUuid, “message”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • Notice here that the entityType is “PRODUCT” instead of “ANNOTATION.” These Comments will be appended to the overall Product Page.
  • After successfully creating a Comment, the response body will return the uuid of the Comment, which is needed to edit or delete the Comment.

Edit a Comment

  • Comments can also be edited after they are posted:

Method: PUT
Endpoint: /v1/comments
Sample Request Body: { “entityUuid”: “string”, “message”: “string”, “uuid”: commentUuid }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The entityUuid is the ID of the Entity you are updating. For example, if you are editing a Product Comment, then the entityUuid is the productUuid. If you are editing the response to an Annotation, then the entityUuid is the annotationUuid.
  • The uuid is the ID of the Comment itself.

Retrieve the Comments for a Product

  • All of the Comments for a Product can be retrieved with the following endpoint:

Method: POST
Endpoint: /v1/comments/search
Sample Request Body: { “entityType”: “PRODUCT”, “entityUuid”: productUuid, “page”: 1, “size”: 10 }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The list of Comments retrieved can be filtered by Entity Type, Entity Uuid, Page, and Size. In this example, we only want the Product Comments, so the entityType is set to “PRODUCT”. If we wanted the list of replies to an Annotation, however, we could change the entityType to “ANNOTATION”. The entityUuid is again, either the uuid of the Product or the Annotation for which to retrieve Comments. Page and Size can also be changed to determine which subset of Comments to retrieve, and how many to retrieve per API call.

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.