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 Assets 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 Workspace 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 Workspace. As with the first Refresh Token, this allows you to interact with this Workspace, but in order to begin interacting with another Workspace you will have to re-generate the Refresh Token. Again, Organization Owners/Admins do not generate a Refresh Tokens for each Workspace, 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 Workspaces
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 Workspaces, 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 Workspaces, and so although they may only actually apply to a subset of an Organizations Workspaces, they are still ultimately contained by the Organization. You can view more information on Webhooks here.
Next, Workspaces act as containers for your Assets, Projects and any entity associated with them such as Tags and Attachments. These are referred to as both Workspaces on the Platform, but data associated with them are referred to as client- the API which is the legacy nomenclature. With Workspaces, users can be added such that they only have access to a subset of Workspaces 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 Workspaces 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 Workspace Refresh Token if your user access requires this. Additionally, the UUID of an Organization or Workspace may be needed for a number of endpoints in the Admin API, for example when creating a Asset you must pass the Workspace UUID that it is to be added to.
To view a guide on retrieving lists of Organizations and Workspaces you are associated with, view this guide.
Asset
Searching Assets
The Admin API allows one to interact with most Asset related functions including searching for and retrieving Asset information, creating Assets and uploading 3D files, and deleting Assets. By utilizing the API the full process of creating and managing Assets can be automated, and by utilizing Webhooks this can be streamlined to require minimal API calls.
When interacting with Assets that already exist, their Asset UUID will usually be needed, whether for the purpose of pulling / downloading the 3D asset or generating and embedding the iFrame of the asset elsewhere. Webhooks can be set up to send asset information when certain events fire such as an asset 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 Assets you have access to based on a number of search parameters in order to retrieve a list of assets and their information. With this list, you can then iterate to find the correct asset and utilize its UUID. For a guide on searching assets and the options available when filtering the results, view this guide.
The UUID isn’t the only piece of information for an asset that may be relevant, and in some cases you may have a asset’s UUID either from a Webhook call or it was stored locally, and you need to use this to retrieve other information from the Asset such as Comments or Attachments. For these scenarios, you can directly retrieve a Asset’s information using it’s UUID. View this guide for more information.
Creating Assets
Assets 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 Asset, getting a signed-url, and uploading the 3D file to this signed-url. Additionally, when creating an Asset, you can add a multitude of additional metadata including Tags and Attributes, as well as add the asset 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 an Asset, you can also update existing assets, either updating the metadata or re-uploading the 3D asset. To view our guide on creating and updating assets, go here.
Downloading Assets
Once an Asset 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.
Projects
Projects are a new feature which allow another increased organizational capabilities. These are entities contained within a Workspace which allow you to organize your Assets by linking them through a Project. Projects can be viewed as directories which can contain both Assets and sub-Projects. From the Project page of a Workspace, you can view all root Projects in a grid, or view the full Workspace as a folder tree with the names of all root Projects, sub-Projects, and Assets.
The Admin API allows full control over the creation and linking of Projects and Assets. The new Projects endpoints allow you to create, update, search all Live Projects, as well as link and unlink Live Assets to any Live Project. For more information on creating/updating Projects, view this guide; to learn more about Project data retrieval, view this guide.
In addition to the new Projects endpoints, the Asset creation/updating endpoint has been updated to include the option to link the Asset to a Project or create a new Project and auto-link the two.
Tags and Tag Groups
The VNTANA Platform offers a number of different ways to apply identifying information to your Assets which can be used when searching for Assets to narrow down or pinpoint the results. One such feature are Tags and Tag Groups. These are Workspaces 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 Assets 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 Asset using either the embed link or iFrame. Using the Admin API, one can create, retrieve, and add attachments to Annotations on any Asset, 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 Assets. Unlike Annotations, these are not shown in 3D space, and instead are linked to various other entities including a Asset, 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 Asset, the API can also be leveraged to upload attachments directly to the Asset. These attachments can serve a variety of use cases including renders of the Assets 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 Assets 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.