API – Download Thumbnails

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 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.

You can download the Thumbnail that is generated for your Product using both the Admin API and the Public API. These can be pulled for internal records or to be used as a Product thumbnail on your website where the VNTANA Webviewer has been integrated, and these methods mesh seamlessly with the Webhooks feature offered by the VNTANA Platform.

Note: This guide is only on downloading a Product’s thumbnail, to see about downloading the Asset itself, view this guide.

Note: In order to download the thumbnail or asset itself, the Product must be ‘Published’ on the Platform, meaning it is in the either Live Internal or Live Public state.

Download Thumbnail via Admin API

As with all Admin API actions, you must first authenticate with the VNTANA Platform. You can view our Authentication guide for a detailed look at the steps involved, or view the below summary.

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.

In order to download the thumbnail for a Product via the Admin API, you will need three UUID’s:

clientUuid: The UUID of the Client / Folder containing the Product in question.
productUuid: The UUID of the Product the thumbnail belongs to.
thumbnailUuid: The UUID of the Thumbnail itself, obtained with the Product’s information when doing a Product Search.

If the clientUuid is not obtained in the authentication process, then you can use the following endpoint to retrieve a list of Clients / Folders and store the correct UUID.

Get Clients / Folders Example

The Request structure is as follows:

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

The Response structure is as follows:

{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“slug”: “some-client-slug”,
“name”: “Some Client,
“role”: “ORGANIZATION_ADMIN”,
“imageBlobId”: “string”,
“created”: “2020-01-31T19:17:23.972”
}
]
}
}

Next, retrieving the productUuid and thumbnailUuid can both be retrieved using a Product search. View our guide on Searching for Products for a more detailed look at the options available, otherwise you can use the below to search based on name:

Searching for Product Example

The Request is structured as follows:

Method: POST
Endpoint: /v1/products/clients/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘page’ : 1,
‘size’ : 10,
‘clientUuids’ : [ ‘some-client-uuid’ ],
‘searchTerm’ : ‘string’,
‘name’ : ‘string’
}

The Response is structured as follows:

{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“clientUuid”: “string”,
“clientSlug”: “some-client-slug”,
“name”: “string”,
“locations”: [],
“tags”: [],
“variantGroups”: [],
“status”: “LIVE”,
“conversionStatus”: “COMPLETED”,
“asset”: {
“generationRequestUuid”: “string”,
“thumbnailBlobId”: “string”,
“assetBlobId”: “string”,
“assetOriginalName”: “string”,
“materialBlobId”: null,
“conversionFormats”: [
“GLB”,
“USDZ”
],
“models”: [
{
“uuid”: “string”,
“conversionFormat”: “GLB”,
“modelBlobId”: “string”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null
},
{
“uuid”: “string”,
“conversionFormat”: “USDZ”,
“modelBlobId”: “string”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null
}
]
},
“created”: “2022-06-26T22:21:26.744”,
“attributes”: [],
“updated”: “2022-06-26T22:34:57.042706”,
“malwareProcessingStatus”: null
}
]
}
}

The searches are fuzzy, meaning they return results based on relevance. Unless every Product name is quite unique, you’ll likely have to iterate over the results to match the name exactly.

Note: Products in the Draft state will not be returned by search endpoints, only those in either the Live Internal or Live Public state will be accessible.

Alternatively, if you have a Webhook setup to notify you of the event product.completed which fires when a product has completed the Optimization process, you can use the productUuid sent in the Webhooks payload to your endpoint to pull the Products data using the below endpoint:

Method: GET
Endpoint: /v1/products/some-product-uuid
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }

You can view the guide on Retrieving a Product by UUID for more details on this method.

These will return the following data, which contains the thumbnailBlobId:

{
“response”: {
“grid”: [
{
“asset”: {
“assetBlobId”: “string”,
“assetOriginalName”: “string”,
“conversionFormats”: [
“GLB”
],
“generationRequestUuid”: “string”,
“materialBlobId”: “string”,
“models”: [
{
“conversionError”: {
“code”: “string”,
“description”: “string”
},
“conversionFormat”: “GLB”,
“conversionStatus”: “PENDING”,
“modelBlobId”: “string”,
“uuid”: “string”
}
],
“thumbnailBlobId”: “string”
},
“attributes”: [
{
“key”: “string”,
“value”: “string”
}
],
“clientSlug”: “string”,
“clientUuid”: “string”,
“conversionStatus”: “PENDING”,
“created”: “2022-06-30T15:54:17.954Z”,
“locations”: [
{
“name”: “string”,
“uuid”: “string”
}
],
“malwareProcessingStatus”: “FAILED”,
“name”: “string”,
“status”: “DRAFT”,
“tags”: [
{
“name”: “string”,
“uuid”: “string”
}
],
“updated”: “2022-06-30T15:54:17.954Z”,
“uuid”: “string”,
“variantGroups”: [
{
“name”: “string”,
“uuid”: “string”
}
]
}
],
“totalCount”: 0
},
“success”: true
}

As you can see, the thumbnailBlobId can be retrieved from response > grid > asset > thumbnailBlobId.

Now, with all three UUID’s and valid authentication, you can make the following call to download the thumbnail:

Method: GET
Endpoint: /v1/products/{productUuid}/clients/{clientUuid}/thumbnails/{thumbnailBlobId}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: height, width

These will take the query parameters height and width, which need not be included. In Postman, you will be able to see the thumbnail in the response console, otherwise this data will have to be streamed into a file or however you intend to utilize it.

Downloading Thumbnail via Public API

In order to download the Thumbnail via the Public API, you will need three values:

productUuid: The UUID of the product, can be obtained via Public API call as well.
clientSlug: Unique name-based identifier for the Client / Folder.
organizationSlug: Unique name-based identifier for the Organization.

The clientSlug and organizationSlug are based on the names of the Client / Folder and Organization. On the VNTANA Platform, Organization and Client / Folder names need not be unique, instead a slug is generated based on the name which is unique. These can be found in the URL of the Client / Folder 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:

Method: POST
Endpoint: https://api.vntana.com/products/organizations/{organizationSlug}/clients/{clientSlug}
Body: {
“attributeKey” : “string”,
“attributeValue” : “string”,
“page” : 1,
“size” : 10,
“description” : “string”,
“searchTerm” : “string”,
“tagName” : “string”,
“locationName” : “”
}

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, which can be entered into the following endpoint to retrieve the thumbnail’s data:

Method: GET
Endpoint: https://api.vntana.com/products/{productUuid}/organizations/{organizationSlug}/clients/{clientSlug}

Upon successful retrieval of the thumbnail data it can either be saved to a file or handled as you see fit.

Postman Collections

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.

Resources