API – Download Posters

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.

You can download the Poster image (or Thumbnail) that is generated for your 3D Asset using both the Admin API and the Public API. These can be pulled for internal records or to be used as an Asset poster 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 an Asset’s Poster, to see about downloading the Asset itself, view this guide.

Note: In order to download the Poster or original file itself, the Asset must be ‘Published’ on the Platform, meaning it is in the either Live Internal or Live Public state.

Download Poster Image 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 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 Workspace 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 poster for an Asset via the Admin API, you will need three UUID’s:

clientUuid: The UUID of the Workspace containing the Asset in question.
productUuid: The UUID of the Asset the poster belongs to.
thumbnailUuid: The UUID of the poster itself, obtained with the Asset’s information when doing an Asset Search.

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

Get Workspace 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 an Asset search. View our guide on Searching for Assets for a more detailed look at the options available, otherwise you can use the below to search based on name:

Searching for Asset 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 Asset name is quite unique, you’ll likely have to iterate over the results to match the name exactly.

Note: Assets 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 an asset has completed the Optimization process, you can use the productUuid sent in the Webhooks payload to your endpoint to pull the Asset’s 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 an Asset 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 Poster:

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

Downloading Poster Image via Public API

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

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

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

The clientSlug and organizationSlug are based on the 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 assigned name and 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:

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 Poster’s data:

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

Upon successful retrieval of the poster 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