API – Product Creation and Updating

API Changes Effective July 13th, 2023, an API change was made regarding the publish status of products on the VNTANA Platform. The product creation/update parameter autoPublish was replaced with publishToStatus. See the section in this guide on Publish Status for more details.

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.

Authentication Steps Summary

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.
  
  1
  
  2
  
  3
  
  4
  
  {
  
  ‘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.
  
  1
  
  2
  
  3
  
  4
  
  5
  
  {
  
  ‘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:

Method: POST
Endpoint: /v1/products
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“attributes” : {},
“publishToStatus” : “DRAFT” or “LIVE_INTERNAL” or “LIVE_PUBLIC”,
“status” : “DRAFT” or “LIVE_INTERNAL”,
“clientUuid” : “{{clientUuid}}”,
“description” : “”,
“locationsUuids” : [],
“modelOpsParameters” : {
“DRACO_COMPRESSION” : {
“enabled” : “true”
},
“OPTIMIZATION” : {
“desiredOutput” : “AUTO”,
“obstructedGeometry” : “true”,
“poly” : “50000”
},
“PIVOT_POINT_ALIGNMENT”: {
“pivotPoint”: “bottom-center” “or” “center”
},
“TEXTURE_COMPRESSION” : {
“lossless” : “true”,
“maxDimension” : “1024”,
“aggression” : “3”
}
},
“name” : “{{name}}”,
“pipelineUuid” : “{{pipelineUuid}}”,
“presetUuid” : “”,
“tagsUuids” : []
}

Important: autoPublish has been replaced by publishToStatus with possible values “DRAFT”, “LIVE_INTERNAL”, and “LIVE_PUBLIC”. Additionally, the parameter status is intended for use cases when you need to create an empty Product (no 3D asset) but still want the Product to be set to LIVE_INTERNAL and thus be accessible via the API.

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.

Retrieving Pipeline Data Example

The endpoint to retrieve data for each Pipeline is:

Method: GET
Endpoint: /v1/pipelines
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }

A successful request will return the following Response Body containing a list called ‘grid’ which has each Pipeline name and UUID

{
“success”: true,
“errors”: [],
“response”: {
“pipelines”: [
{
“name”: “Browzwear”,
“uuid”: “87d414ec-e1f3-4fe3-a5f9-ac4b9cdc51f1”
},
{
“name”: “Clo”,
“uuid”: “c4a964c8-2203-4d02-ba37-4601ea6d157b”
},
{
“name”: “3D Scan”,
“uuid”: “fa2dc262-a785-4b19-b36a-2dae7449b7bb”
},
{
“name”: “Keyshot”,
“uuid”: “1167c16c-f777-43fd-a2a2-2806f8a46a4e”
},
{
“name”: “Modo”,
“uuid”: “ec905489-4f5f-4031-9ee8-d556fcc146ab”
},
{
“name”: “Romans CAD”,
“uuid”: “522c8df2-87a3-4d3f-af1d-4c78387a715f”
},
{
“name”: “Custom Jewelry”,
“uuid”: “30032bc3-5303-473b-80cf-07cdb26d8be5”
},
{
“name”: “Preserve Animations”,
“uuid”: “e29830b1-26d6-4bab-b87f-af4fd7fba93b”
},
{
“name”: “Convert Only”,
“uuid”: “0bea6387-243a-474c-aece-ca152a3d3b2b”
},
{
“name”: “Other”,
“uuid”: “2453de9a-ecf5-418e-9e9d-dd0f85adc904”
},
{
“name”: “No Baking”,
“uuid”: “664a5d17-18d0-4bed-86b6-ab89Bcfa0b23”
},
{
“name”: “Wanna”,
“uuid”: “c39dddde-a357-4934-821c-9a646ab50368”
},
{
“name”: “Force Baking”,
“uuid”: “d16b559f-b16a-4b5e-9e83-3a64bd908a6e”
}
]
}
}

A successful request will return the Product’s information including UUID.

Product Creation Response Sample

An example of the Response Body from a successful Product creation.

{
“success”: true,
“errors”: [],
“response”: {
“uuid”: “some-uuid”,
“name”: “Test Creation”,
“productSessionUuId”: “some-uuid”
}
}

With the product successfully created, a Signed URL must be generated using the UUID.

Method: POST
Endpoint: /v1/storage/upload/clients/products/asset/sign-url
Headers: {
‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
‘Origin’ : ‘https://api-platform.vntana.com’,
}
Body: {
“clientUuid” : “{{clientUuid}}”,
“productUuid” : “{{productUuid}}”,
“resourceSettings” : {
“contentType” : “application/octet-stream”,
“originalName” : “original-file-name”,
“originalSize” : 0
}
}

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:

Method: PUT
Endpoint: signed-url from previous endpoint
Headers: {
‘Origin’ : ‘https://api-platform.vntana.com’,
‘Content-Length’ : 0
}
Body: File binary data must be streamed.

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. An empty or processing product will remain in Draft until an asset is finished optimizing. 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. Note: only products in the Live Internal or Live Public state can be searched for via the API, Draft products will be hidden from the results.

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.

Method: PUT
Endpoint: /v1/products
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“attributes”: {},
“publishToStatus”: “DRAFT” or “LIVE_INTERNAL” or “LIVE_PUBLIC”,
“status” : “DRAFT” or “LIVE_INTERNAL”,
“clientUuid”: “string”,
“deleteAsset”: true,
“description”: “string”,
“locationsUuids”: [],
“modelOpsParameters”: {
“DRACO_COMPRESSION”: {
“enabled”: “true” “or” “false”,
},
“OPTIMIZATION”: {
“desiredOutput”: “AUTO”,
“obstructedGeometry”: “true” “or” “false”,
“poly”: “1000”
},
“PIVOT_POINT_ALIGNMENT”: {
“pivotPoint”: “bottom-center” “or” “center”
},
“TEXTURE_COMPRESSION”: {
“lossless”: “true” “or” “false”,
“maxDimension”: “1024”,
“aggression”: “3”,
“useKTX”: “true” “or” “false”
}
},
“name”: “string”,
“pipelineUuid”: “string”,
“presetUuid”: “string”,
“tagsUuids”: [
“string”
],
“uuid”: “string”
}

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

Publish Status

When publishing your 3D to the VNTANA Platform, there are three main states in which the Product can live. Depending on the state of a Product, the functionality available both via the Admin API and directly on the Platform may be limited. The three states are: Draft, Live Internal, and Live Public. In addition to differences in available functions, there is a cost difference associated with them, for more info on the VNTANA Pricing see this guide.

Draft

The ‘free’ state, you can have unlimited Products on the platform in the Draft state and will only incur charges for a given Product if it is placed in Live Internal or Live Public once during a billing cycle. In this state, the following applies:

View the Optimized asset on the Platform.
- The viewer will not load in external sites making Draft products unshareable.
Download the Original 3D asset.
- You cannot download any of the optimized versions.
You will not be able to search for the Product via the API.

Live Internal

The ‘private’ paid status, this will allow you the same functionality as the Draft status with the added functionality of downloading the Optimized assets. In this state, the following applies:

View the Optimized asset on the Platform.
- The viewer will not load in external sites.
Download the Original and Optimized assets.
Full access via the Admin API.

Live Public

The ‘public’ paid status, this will allow full functionality for the product. In this state, the following applies:

View the Optimized asset on the Platform and share/embed the viewer externally.
Download the Original and Optimized assets.
Full access via the Admin API.

Note: While the Live Internal and Live Public are separate states and both can trigger a charge, they are not charged separately. You will be charged no more than once per asset and can swap between Live Internal and Live Public without incurring additional charges.

Publishing w/o 3D Asset

When utilizing a workflow which sees the creation of a multitude of Products before their 3D assets are available to upload, it is important to still be able to retrieve these Products via the API to later edit or upload their assets. In order to accomplish this, an additional parameter needs to be passed in the Product creation body called status with a value of LIVE_INTERNAL. This will ensure the Product behaves the same as a Live Internal product which has a 3D asset as normally a Product can’t be in a Live state without an asset.

Resources