API Base URL: https://api-platform.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 folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.
A key integration with the Platform is access to the core VNTANA feature, Product creation and subsequent Optimization of the uploaded asset. With the API endpoints involved in Product creation, you can automate the process of uploading assets for Optimization, updating existing Products, and downloading the optimized assets (link to download guide). Additionally, when coupled with Webhook’s that monitor the conversion status of newly created Product’s you can reduce the amount of API calls made and more directly track an individual Product’s progress. For more information on Webhook’s view this guide.
As with all endpoints in the VNTANA Admin API, you must first properly authenticate, generating a Refresh Token as below. View this guide for a more complete look at 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 Clients / Folders and store the needed UUID.
-
Pass the x-auth-token in the Request Headers.
-
This step can be skipped if the Client / Folder UUID is already stored locally.
-
-
Generate a Refresh Token for the Client / Folder (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.
-
Creating a Product
The process of creating a Product involves three key endpoints. First, the actual Product must be created. On the VNTANA Platform a Product is merely a container which can be viewed / accessed which holds the original and optimized models, shows the optimized model in the VNTANA viewer, and displays metadata set by you at Product creation. The endpoint for the step is as follows:
A key parameter is the pipelineUuid. This refers to the Pipeline you select when creating a product on the Platform and is required. If you do not already know the pipelineUuid you need to use, you can retrieve the list of Pipeline’s using the below example.
A successful request will return the Product’s information including UUID.
With the product successfully created, a Signed URL must be generated using the UUID.
This endpoint also requires the size in bytes of the file to be uploaded, as well as the name of the file to be uploaded. Finally, the 3D file can be uploaded using the newly generated signed url as the endpoint as follows:
Once the model has been successfully uploaded it will take some time to optimize depending on the complexity of the 3D model’s geometry and / or file size, but will have a conversion status of COMPLETED once it is ready to be published and the viewer can be loaded externally. To find out the conversion status you can use the search endpoint (Search guide) and use the statuses parameter or set up a Webhook that subscribes to the Product events related to conversion status. View this guide to learn more about integrating with Webhooks.
Postman - Create Product
To test this process, you can use the following Postman Collection. You can view a general guide on using our collections here, but overall you will need to set the necessary global variables found within the collection and decide which form of authentication you wish to use (key or email / pass). It is set to run as one complete collection, however if you wish to run each endpoint individually you need only activate the deactivated headers and ensure the global variables or local variables are set for each endpoint.
Once again, the final endpoint requires the size of the file in bytes, and the file data must be streamed. In Postman, you must select the ‘binary’ Body data type and set the file. Additionally, you may need to permit Postman to upload files from outside of the Postman workspace as this setting may not be the default. Simply go to File > Settings, and in the General tab look for Working Directory to turn on ‘Allow reading files outside working directory’.
Create Product Collection
Updating a Product
In addition to creating a Product, you can update existing Products (so long as they are not currently being processed by the Optimizer). This will allow you to either add metadata such as Tags, Attributes, or a Description, make changes to data such as the Product’s name, or upload a new / fixed 3D model to have it Optimized. The data passed to the endpoint is similar to that of Product creation, however it does require the UUID of the Product to create.
The endpoints for this are almost exactly the same as creating a product with the only difference being the use of the PUT endpoint Update Product instead of POST endpoint Create Product. The collection includes the endpoints to generate a signed URL and upload the asset, though it is possible to just update the data of a Product and leave the asset in tact, so running those endpoints is not necessary. If the deleteAsset parameter is set to true it will leave the Product empty unless you follow up with the asset upload.
Update Product Collection