The VNTANA Platform exposes a number of features to users via the API in both Public and Admin API sets. The Public API offers a limited number of commands to access information on your Products without the need for authentication, while the Admin API offers a much wider range of commands to more completely integrate the VNTANA Platform into your workflow or e-commerce site. To view documentation on all of the endpoints available in the Public API, visit this page, and to view documentation on all of the endpoints available in the Admin API, visit this page. The URL’s to use with these are as follows:
Public API Base URL: https://api.vntana.com
Admin API Base URL: https://api-platform.vntana.com
This overview will cover the key features available through the Admin API while linking to our other guides for more detailed explanations and examples.
Authentication
The Admin API always requires proper authentication with the VNTANA Platform in order to utilize any of its methods. This can be achieved using either your VNTANA Platform email and password as well as an Authentication Key, and involves 3-5 steps to obtain a Refresh Token for the Organization or Client / Folder you wish to work with.
You will begin the process by retrieving an x-auth-token using the login credentials of your choosing. With this token you will then generate a new x-auth-token called a Refresh Token for the specific Organization you wish to work in. This token allows you to make further calls to the API without need to re-authenticate each time. If you do not have Organization Owner or Organization Admin level access, you must then generate a third x-auth-token also called a Refresh Token that corresponds to a specific Client / Folder. As with the first Refresh Token, this allows you to interact with this Client / Folder, but in order to begin interacting with another Client / Folder you will have to re-generate the Refresh Token. Again, Organization Owners/Admins do not generate a Refresh Tokens for each Client / Folder, they only generate a Refresh Token for an Organization.
To see a detailed guide on the authentication steps, view this guide, or to see more on VNTANA’s use of x-auth-token’s in the authentication process, view this guide.
Generating an Authentication Key
As already mentioned, authentication can be accomplished using an Authentication Key. It is recommended that you use these tokens when integrating the VNTANA Platform via the Admin API as the key can be stored locally and used for quick authentication as opposed to storing or hard-coding an email and password. To generate a key for an account, follow these steps:
Step 1
To retrieve your Authentication Token you will need to log in to the VNTANA Platform and navigate to the “My Profile” page to generate your token. Do this by clicking on your profile icon in the upper right corner of the webpage:
Step 2
On the next screen, three tabs will appear: ‘Profile’, ‘Password’, and ‘Authentication Key’. Click on the ‘Authentication Key’ tab to view your token.
Step 3
The first time you visit this tab you will simply see a button labeled “Generate”, clicking this will generate the Authentication Token for your user account. You can click the copy icon on the right of the generated token to copy it to your clipboard or manually copy it.
If you lose your token, you will have to re-generate it on the Platform by following the same steps.
Organizations and Clients / Folders
A key concept to understand when utilizing the Admin or Public API is how entities are organized on the VNTANA Platform. Users belong first to an Organization on the Platform. This is the highest level of structure users will see when visiting the Platform. The Organization acts as a container for such entities as Clients / Folders, Webhooks, and Users. Though all users in an Organization see the Organization, not all users can access all content in an Organization. For more information on User Access levels, view this guide. Additionally, Webhooks work by subscribing to events within certain Clients / Folders, and so although they may only actually apply to a subset of an Organizations Clients / Folders, they are still ultimately contained by the Organization. You can view more information on Webhooks here.
Next, Clients / Folders act as containers for your Products, Configurators, and any entity associated with them such as Tags and Attachments. These are referred to as both Clients and Folders in order to clear up any confusion as on the Platform they are called ‘Folders’ but in the API documentation they are called ‘Clients’ which is a legacy naming convention. With Clients / Folders, users can be added such that they only have access to a subset of Clients / Folders and not to the entire Organization. These users will not have full access to the Admin API, but can still utilize quite a bit of the functionality and must generate a Refresh Token for the Client / Folder they wish to work with.
In order to properly authenticate, the UUID of the Organization to generate a Refresh Token must be passed in the request, and although this UUID can be stored locally, generally you will have to retrieve a list of Organizations in order to get this UUID. The same is needed for generating a Client / Folder Refresh Token if your user access requires this. Additionally, the UUID of an Organization or Client / Folder may be needed for a number of endpoints in the Admin API, for example when creating a Product you must pass the Client / Folder UUID that it is to be added to.
To view a guide on retrieving lists of Organizations and Clients / Folders you are associated with, view this guide.
Product
The Admin API allows one to interact with most Product related functions including searching for and retrieving Product information, creating Products and uploading 3D files, and deleting Products. By utilizing the API the full process of creating and managing Products can be automated, and by utilizing Webhooks this can be streamlined to require minimal API calls.
Searching Products
When interacting with Products that already exist, their Product UUID will usually be needed, whether for the purpose of pulling / downloading the 3D asset or generating and embedding the iFrame of the Product elsewhere. Webhooks can be set up to send Product information when certain events fire such as a Product being created or completing its optimization, but when a Webhook isn’t feasible and the UUID needs to be retrieved on demand, you can execute a search of the Products you have access to based on a number of search parameters in order to retrieve a list of Products and their information. With this list, you can then iterate to find the correct Product and utilize its UUID. For a guide on searching Products and the options available when filtering the results, view this guide.
The UUID isn’t the only piece of information for a Product that may be relevant, and in some cases you may have a Product’s UUID either from a Webhook call or it was stored locally, and you need to use this to retrieve other information from the Product such as Comments or Attachments. For these scenarios, you can directly retrieve a Product’s information using it’s UUID. View this guide for more information.
Creating Products
Products are the key feature of the VNTANA Platform, and the Admin API allows you to automate the process of creating and uploading your 3D assets. The process consists of three steps: creating the Product, getting a signed-url, and uploading the 3D asset to this signed-url. Additionally, when creating a Product, you can add a multitude of additional metadata including Tags and Attributes, as well as add the Product to a Configurator / Variant Group. You can set all the same Optimization settings as are available on the Platform, however you cannot load any saved Optimization Settings Presets at this time.
In addition to creating a Product, you can also Update existing Products, either updating the metadata or re-uploading the 3D asset. To view our guide on creating and updating Products, go here.
Downloading Assets
Once a Product has been created and a 3D asset optimized, you can utilize the API to download the various formats of the 3D asset as well as the Preview Image. For downloading the 3D asset, you can use both the Public and Admin API to download the Original, GLB, FBX, and USDZ formats. Likewise, you can leverage both the Public and Admin API’s to download the Preview Image as a PNG. View this guide to learn how to download the 3D asset, and this guide to learn how to download the Preview Image.
Tags and Tag Groups
The VNTANA Platform offers a number of different ways to apply identifying information to your Products which can be used when searching for Products to narrow down or pinpoint the results. One such feature are Tags and Tag Groups. These are Client / Folder specific, and can be used to indicate any piece of information you wish, including an entirely unique identifier such as a SKU or a material type like Cotton. Additionally, you can create a Tag group to add Tags into which makes it easier to retrieve a list of Tags and their UUID’s for use when searching for Products or Configurators. View this guide here to see how to utilize the API to create and use Tags and Tag Groups.
Annotations
Annotations are a feature which allows teams to place comments on their 3D assets in the 3D space of the viewer, letting your team highlight problem areas of an asset or simply link resources to specific components. These are not publicly viewable and as such will not show when viewing the Product using either the embed link or iFrame. Using the Admin API, one can create, retrieve, and add attachments to Annotations on any Product, however due to the fact that these exist in 3D space it may not be desirable to create Annotations using the API. If you do choose to create an Annotation, be careful when passing the parameter dimensions as this must be passed as a stringified json object, and all inner quotes need to be escaped as so: '{\'position\': \'0.0m 0.0m 0.0m\',\'normal\': \'0.0m 0.0m 0.0m\'}'. For more information on utilizing the Admin API for Annotations, view this guide.
Comments
Comments are another feature like Annotations that allow your team to communicate directly on the Platform regarding particular Products. Unlike Annotations, these are not shown in 3D space, and instead are linked to various other entities including a Product, Configurator, and even an Annotation. The Admin API can be used to create, edit, delete, and add attachments to Comments. For a more detailed look at using the API to leverage Comments, view this guide.
Attachments
In addition to Comments and the variety of metadata that can be applied to a Product, the API can also be leveraged to upload attachments directly to the Product. These attachments can serve a variety of use cases including renders of the Products themselves. Attachments can also be added via the API to Comments and Annotations. View the Attachments guide here for a more detailed look.
Webhooks
Webhooks and the Admin API offer a great way to improve any integration with the VNTANA Platform. By utilizing Webhooks to subscribe to a variety of events, you can reduce the number of API calls necessary to automate the handling of Products from upload to embedding in your e-commerce site. Additionally, you can utilize the API to create Webhooks and update them, as well as retrieve the Secret Key used to validate a Webhooks request or regenerate the Secret Key. For a detailed guide on creating Webhooks both manually and via the API, as well as sample endpoints for you to create to receive the request from the Webhook, view this guide.