Admin API Base URL: https://api-platform.vntana.com
Public API Base URL: https://api.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.
Another key feature of the VNTANA Platform is the ability to download the Original file that was uploaded as well as the GLB, FBX, and USDZ formatted versions of the Optimized 3D model when applicable. This is possible using both the Admin API and the Public API.
Note: In order to download the thumbnail or associated files, the Asset must be ‘Published’ on the Platform, meaning it is in either the Live Internal or Live Public state.
Downloading File via Admin API
As with all endpoints in the Admin API, you must first obtain the appropriate level of authentication by generating a Refresh Token. View this guide to learn more about authentication.
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 Client 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 need to make a request to retrieve the UUID of the Asset(s) you wish to download a file for. If you have the UUID stored locally, this step can be skipped. For more information on how to search for Assets on the Platform, view this guide. Note: Assets that are in the Draft state will not be returned in search requests, only those in Live Internal or Live Public.
Use this endpoint to search for an Asset to retrieve its UUID.
Next, you will also need to retrieve the clientUuid if you don’t already have it. You can use the following endpoint to retrieve a list of Workspaces and pull the correct uuid. Note: If you have a Webhook configured to notify you of a product.completed event, meaning it has finished Optimization and is ready to be downloaded, the clientUuid will be passed in the payload sent by the Webhook.
The Request structure is as follows:
The Response structure is as follows:
Important: When dealing with Assets containing 3D files, there are likely multiple formats available for download. To verify the format you wish to download is available, you can retrieve the necessary data from a search request and see the optimized and converted formats in the responses asset -> models section. The models parameter will contain the available formats and each one’s conversionStatus will indicate whether it completed conversion or failed.
With the Asset UUID(s) in hand, you can call one of the following endpoints to download the file:
The difference between the two is in the endpoint URL, for the original file you pass asset in the URL and for the optimized you pass model as well as a query parameter for the format (GLB, FBX, or USDZ). The data from the endpoint will need to be streamed into a file and unlike other endpoints that return the data in the Response Body, the entire Response content will simply be the data that needs to be streamed into a file.
Important: If the Asset you are looking to download is a non-3D file, you are simply using the first endpoint /download/asset.
Downloading Model via Public API
You can also leverage the Public API to download the Optimized versions of your Assets, as well as the Original. The endpoint will require 4 parameters:
- productUuid: The UUID of the Asset to download the files for.
- blobId: The UUID of the converted file, unique for each format (GLB, FBX, or USDZ).
- organizationSlug: Unique name-based identifier for the Organization.
- clientSlug: Unique name-based identifier for the Workspace.
The clientSlug and organizationSlug are based on the (original) names of the Workspace and Organization. On the VNTANA Platform, Organization and Workspace names need not be unique, instead a slug is generated based on the originally entered name which is unique. These can be found in the URL of the Workspace or Organization in question. For example: https://platform.vntana.com/some-org-slug/some-client-slug.
The productUuid can be retrieved using the following Public endpoint:
Note: The base URL of the Public API is different than that of the Admin API.
There are a few different options to filter the results of the search, but only page and size are actually required. This will return the productUuid in the Response body, as well as each formats blobId:
The blobId is the parameter modelBlobId found in response > grid > asset > models for each conversion format, whereas it’ll be assetBlobId found just in response > grid > asset. With all the necessary parameters, the model can be downloaded using the following endpoint:
Postman Collection
To test these endpoints download the below Postman collections, containing examples for both the Public and Admin API processes. To use these collections, simply set the necessary global variables and run the collection as a whole, selecting which endpoints to make use of. If you wish to run each endpoint individually, simply activate the deactivated headers and ensure each endpoint has the necessary data (whether from global variables or directly entered into their endpoint specific locations). You can view our general Postman guide here.