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.

Authenticating a Specific Client (Retrieve the Refresh Token)

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

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

  • The refreshToken here is the same refreshToken retrieved from authenticating the Organization in Step 3 and passed in the headers in Step 4. The Client UUID can be found from the list of Clients returned in the previous step (Step 4).
  • On successful authentication to the selected Client, you will receive another X-AUTH-TOKEN Response Header. This is the Refresh Token for this Client. Please keep in mind that this Refresh Token is different from the Organization Refresh Token from Step 3.
  • You can now access your Products and Client related items (e.g. Locations, Tags) for this 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 Client-specific Refresh Token returned in the Response Headers of the previous step (Step 5).

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 Client-specific Refresh Token from Step 5 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 Client-specific Refresh Token from Step 5 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-8 in order to retrieve the Clients in that Organization, authenticate into the desired Client, and then retrieve the Products, Locations, and Tags for that Client. 

One of the important concepts as part of the VNTANA Platform are Products. Products are essentially an overarching entity for 3D assets that hold not only the raw (original) 3D asset, but also the converted and optimized versions in GLB and USDZ formats, as well as the metadata that goes along with any 3D models.

Products

Create a Product

  • Use the following endpoint to create a Product:

Method: POST
Endpoint: /v1/products
Sample Request Body: {
“clientUuid”: “[CLIENT UUID]”,
“name”:”Sample Product Name”,
“pipelineUuid”:”[PIPELINE UUID]”,
“autoPublish”:false,
“modelOpsParameters”:{
“OPTIMIZATION”:{
“desiredOutput”:”AUTO”,
“obstructedGeometry”:”false”,
“poly”: “0”
},
“DRACO_COMPRESSION”:{
“enabled”:”false”
},
“TEXTURE_COMPRESSION”:{
“aggression”:”4″,
“maxDimension”:”2048″,
“lossless”:”false”
},
“AR_SCALING”:{
“dimension”: “x”,
“size”: “1.5”
}
},
“attributes”:{
“attribute key”:”attribute value”
}
Headers: { “x-auth-token”: “Bearer ” + [X-Auth Refresh Token] }

  • clientUuid is the Client UUID. This is a required parameter.

  • name is the name of the product. This is a required parameter.

  • pipelineUuid is the UUID of the pipeline you would like to process your model with. You can retrieve the pipeline UUID with the /v1/products endpoint. Please refer to the API documentation for details.

  • autoPublish is the boolean flag that determines if the product should be auto-published once the processing is COMPLETE. It is important to note that you can only auto-publish if you have Client Admin or Organization Admin privileges.

  • modelOpsParameters is a nested object that defines 3D and texture optimization and compression parameters.
    • OPTIMIZATION defines the 3D model decimation levels (reduction of polygon and vertex count). If you set it as null, no optimization will happen.
      • desiredOutput: If set to AUTO, the optimization smart algorithm will automatically detect the level of decimation to achieve the smallest file possible at the best quality possible. If set to CUSTOM, the optimization process will look for the poly count defined by the poly parameter.
      • poly: An integer value that defines the maximum polygon count you desire to achieve.
      • obstructedGeometry: (beta) A boolean flag that defines whether you would like to remove parts and polygons of the model that are not visible to the outside world. This helps to reduce the model poly count further. Keep in mind this feature is currently in beta testing and may not give you the best results. We recommend using this only if you would like to experiment with it.
    • DRACO_COMPRESSION enables Draco Compression on the model. Draco compression only applies to the final GLB files. It helps reduce the file size up to 5 times.
    • TEXTURE_COMPRESSION enables Texture Compression if it is defined. If you pass null as the value, the texture compression will be disregarded.
      • lossless: A boolean flag that determines the method of compression. The VNTANA Platform currently supports Lossless and Lossy comparisons. Setting lossless to false will automatically use lossy compression.
      • aggression: Determines the compression aggression, but only for lossy compression. If you choose lossless as the compression type, the aggression parameter will not make any difference. Our recommended aggression level is 4.
      • maxDimension: Defines the maximum power of two size of a texture. This parameter accepts 512, 1024, 2048, 4096, and -1 as values. If set to -1, texture compression will preserve the original texture sizes.
    • AR_SCALING is an optional utility designed for Web AR. This option allows you to resize the model, so it shows in the correct size in the Web AR experience.
      • dimension: Defines the axis at which you desire to proportionally scale the model.
      • size: The size in meters.
  • attributes allow you to define extra metadata that you can associate with your product. For example, you can define an alternative SKU or vendor product ID as an attribute you would be able to search by. It accepts key value pairs. There is no limit to how many attributes you can define per product.
  • On successful creation of a Product, the uuid of the Product will be returned in the response body. You will need the uuid for uploading the actual 3D asset that will be processed based on the parameters you have defined for your product. You will also need the UUID to search, edit, or delete the product.

Edit or Delete a Product

After you have created a Product, you can always edit it. The request body is almost the same as described in the product creation above with a few additional required parameters.

Method: PUT
Endpoint: /v1/products
Sample Request Body: {
// ALL PARAMETERS DESCRIBED IN THE PRODCT CREATION ABOVE
“uuid”: “[PRODUCT UUID]”,
“deleteAsset”: “false”
}
Headers: { “x-auth-token”: “Bearer ” + token }

  • uuid is the uuid of the product that has been returned after the product has been created.

  • deleteAsset is a boolean flag that determines whether the product should be deleted.

Upload an Asset for a Product

After you have created a Product, you will need to upload the raw 3D for it. The upload process has a few steps. To make sure the upload process is secure, we first require you to retrieve the signed URL through an endpoint. Once you have the signed URL, you will have 15 min to upload the asset. First things first, let’s get the signed URL.

Method: POST
Endpoint: /v1/storage/upload/clients/products/asset/sign-urls
Sample Request Body: {
// ALL PARAMETERS DESCRIBED IN THE PRODCT CREATION ABOVE
“clientUuid”: “[CLIENT UUID]”,
“productUuid”: “[PRODUCT UUID]”,
“resourceSettings”: {
“contentType”: “application/octet-stream”,
“originalName”: “SmpleFileName.glb”,
“originalSize”: [FILE SIZE IN BYTES]
}
}
Headers: {
“x-auth-token”: “Bearer ” + token,
“Origin”:: “The origin domain wher the upload will be coming from”
}

  • clientUuid is the Client UUID. This is a required parameter.
  • productUuid is the Product UUID. This is a required parameter.
  • resourceSettings is the object that defines the details about the origin size and the type of file.
    • contentType is the mime type for the file. For 3D assets, it will usually be application/octet-stream.
    • originalName is the domain where the upload will be originated from.
    • originalSize is the size of the file in bytes.

Now that you have the signed URL, you can trigger the upload process.

Method: PUT
Endpoint: [SIGNED URL]
Sample Request Body:
[file data]

Headers: {
“Content-Length”: [FILE SIZE IN BYTES],
“Origin”:: “The origin domain wher the upload will be coming from”
}

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.