Resources

API – Downloading a Model

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

Another key feature of the VNTANA Platform is the ability to download the Original 3D model that was uploaded as well as the GLB, FBX, and USDZ formatted versions of the Optimized 3D model. This is possible using both the Admin API and the Public API.

Note: In order to download the thumbnail or asset itself, the Product must be ‘Published’ on the Platform.

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

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

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

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

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

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

Once Authenticated, you will need to make a request to retrieve the UUID of the Product(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 Products on the Platform, view this guide.

Use this endpoint to search for a Product to retrieve its UUID.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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’,
‘organizationUuid’ : ‘some-org-uuid’,
‘tagsUuids’ : [],
‘tagName’ : ‘string’,
‘attributeKey’ : ‘string’,
‘attributeValue’ : ‘string’
}

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 Clients / Folders and pull the correct uuidNote: 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:

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

The Response structure is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“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”
}
]
}
}
Important: Support for downloading a converted FBX file is new and as such Products created before Sept. 29, 2022 will not automatically have a FBX file to download. To generate this format you will have to re-process any file you wish to have the FBX for. Additionally, when using the API to download these assets, if you try to download the FBX format of a file that doesn’t have an FBX file it will simply return a 200 status but no file data. To check first whether the FBX exists, in the Search Products response Body look for the FBX conversionFormat in the list of models available and verify the conversionStatus as “COMPLETED”:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 3,
“grid”: [
{
“uuid”: “”,
“clientUuid”: “string”,
“clientSlug”: “string”,
“name”: “7098_1”,
“locations”: [],
“tags”: [],
“variantGroups”: [],
“status”: “LIVE”,
“conversionStatus”: “COMPLETED”,
“asset”: {
“generationRequestUuid”: “string”,
“thumbnailBlobId”: “string.png”,
“assetBlobId”: “string.glb”,
“assetOriginalName”: “string.glb”,
“assetOriginalSize”: 212247520,
“materialBlobId”: null,
“conversionFormats”: [
“GLB”,
“USDZ”,
“FBX”
],
“models”: [
{
“uuid”: “string”,
“conversionFormat”: “GLB”,
“modelBlobId”: “string.glb”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null,
“modelSize”: 52777040,
“optimizationThreeDComponents”: {},
“originalThreeDComponents”: {}
},
{
“uuid”: “string”,
“conversionFormat”: “USDZ”,
“modelBlobId”: “string.usdz”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null,
“modelSize”: 31200469,
“optimizationThreeDComponents”: {},
“originalThreeDComponents”: {}
},
{
“uuid”: “string”,
“conversionFormat”: “FBX”,
“modelBlobId”: “string.fbx”,
“conversionStatus”: “COMPLETED”,
“conversionError”: null,
“modelSize”: 31200469,
“optimizationThreeDComponents”: {},
“originalThreeDComponents”: {}
}
]
},
“created”: “2022-09-28T22:15:52.729”,
“attributes”: [],
“updated”: “2022-09-28T22:46:45.285679”,
“pipelineUuid”: “2453de9a-ecf5-418e-9e9d-dd0f85adc904”,
“malwareProcessingStatus”: null
}
]
}
}

With the Product UUID(s) in hand, you can call one of the following endpoints to download the asset:

1
2
3
4
5
Method: GET
Endpoint: /v1/products/some-product-uuid/download/asset
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘clientUuid’
Example URL: https://api-platform.vntana.com/v1/products/some-product-uuid/download/asset?clientUuid=some-client-uuid
1
2
3
4
5
Method: GET
Endpoint: /v1/products/some-product-uuid/download/model
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘clientUuid’, ‘conversionFormat’ where conversionFormat can be GLB, FBX, or USDZ
Example URL: https://api-platform.vntana.com/v1/products/some-product-uuid/download/model?clientUuid=some-client-uuid&conversionFormat=GLB

The difference between the two is in the endpoint URL, for the original asset 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.

Downloading Model via Public API

You can also leverage the Public API to download the Optimized versions of your Products, as well as the Original. The endpoint will require 4 parameters:

  • productUuid: The UUID of the Product to download the Optimized assets of.
  • blobId: The UUID of the converted asset, unique for each format (GLB, FBX, or USDZ).
  • organizationSlug: Unique name-based identifier for the Organization.
  • clientSlug: Unique name-based identifier for the Client / Folder.

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:

1
2
3
4
5
6
7
8
9
10
11
12
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, as well as each formats blobId:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
“response”: {
“grid”: [
{
“asset”: {
“assetBlobId”: “string”,
“assetOriginalName”: “string”,
“conversionFormats”: [
“GLB”
],
“models”: [
{
“conversionFormat”: “GLB”,
“modelBlobId”: “string”,
“uuid”: “string”
}
],
“thumbnailBlobId”: “string”
},
“created”: “2022-06-30T15:25:22.031Z”,
“locations”: [
{
“name”: “string”,
“uuid”: “string”
}
],
“name”: “string”,
“tags”: [
{
“name”: “string”,
“uuid”: “string”
}
],
“uuid”: “string”
}
],
“totalCount”: 0
},
“success”: true
}

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:

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

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.

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.