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 workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.
Another feature offered on the VNTANA Platform is the ability to upload attachments to your Assets in a variety of forms. There are a lot of allowable file types, see this page for the full list. They can also be uploaded to different entities relating to your Asset. These entities are the Asset itself, Projects, Configurators, Comments, Annotations, and Hotspots. This feature allows you to add reference videos or images to your assets whether for internal use or customer reference. Do note there is a max size allowable for all attachments at 3 GB.
Note: For Hotspots, you cannot attach videos in the same manner, for these they have to be a linked video as Hotspots will be visible to any user with an embed link.
When creating and uploading Attachments via the API, there are two different processes depending on where you are uploading the Attachment. If you wish to upload it simply to an Asset, you can directly do this using a single endpoint. If you want to add it to a Variant Group or a Comment then you will have to first upload the attachment to the Workspace and then add to the Variant Group or Entity. This guide will show the process of uploading an attachment to an Asset and a Variant Group.
Required Initial Steps
Before you can upload the Attachment via the API, you will need to Authenticate. Below is a quick summary of the steps involved, see our guide on Authentication to get a more detailed look at the process.
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 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 UUIDs.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’}Returns the Refresh Token as the Response Header x-auth-token.
The Workspace UUID needs to be retrieved, if it is not stored locally or already retrieved via Authentication, you can search for the Workspace using the API. This endpoint will return a list of Workspaces in the Organization and you can verify the correct one using the name or slug. Below is an example of this endpoint.
The Request structure is as follows:
The Response structure is as follows:
Now that you have a Workspace UUID you are ready to upload the Attachment.
Uploading Attachment
Uploading an attachment to an Asset is the most straightforward of the Attachment methods. With valid authentication and the Workspace UUID in hand, you will just need to obtain the Asset’s UUID that you wish to upload to if it isn’t stored locally, and then upload the attachment directly to it.
Asset Searching
To retrieve the Asset UUID if it isn’t stored locally, you can do a search using a parameter of your choice including Tag UUID, Tag Name, Attribute, or simply the name of the Asset. You can view our guide of Asset Searches here, or to search for an Asset using the expected name, use the below endpoint. Note: Assets in Draft status will not be returned by API searches, only those in either the Live Internal or Live Public state will be returned by the API.
The Request is structured as follows:
The Response is structured as follows:
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.
Variant Group Searching
To add the attachment to a Variant Group, you will need the Variant Group UUID. You can view our Variant Group guide to get a detailed look at searching for Variant Groups, or use the following sample:
The Request is structured as follows:
The Response is structured as follows:
You can use the name in the response to pinpoint the correct Variant Group.
Uploading the File
With the necessary destination information obtained, you can generate a Google Signed URL to upload the file using the following endpoint:
In this example, we want to upload to an Asset, so the parentEntity is an Asset and we can set:
parentEntityUuid : the productUuid of the Asset to upload to
parentEntityType : PRODUCT
The possible options for this endpoint are:
- parentEntityType : PRODUCT, VARIANT_GROUP, ANNOTATION, COMMENT, RENDER
- storeType : ASSET, ATTACHMENT, RENDER
- version : [OPTIONAL] The version number to upload to. Only supported when parentEntityType is PRODUCT.
parentEntityType indicates the type of entity the file is being attached to, while the storeType indicates the way in which the file is being stored. If RENDER is passed, the attachment will be displayed within the Renders tab, as discussed below.
Note: If version is left out, the file will be assigned to the current version. Additionally, while both ATTACHMENT and RENDER can be used as the storeType with version, it only acts as a reference for the Attachment as Attachments are asset level entities. For Renders, these are version level and it will actually assign the renders to that version.
The response will return a requestUuid, blobId and location. The requestUuid and blobId won’t be used when uploading the file, however the location value is the signed-url that’ll be used to upload.
Using the location value, you can make a request like so:
Uploading Renders to the Renders Tab
On the VNTANA Platform, it is possible to generate still renders and 360 turntables as mp4 and gif. While these are displayed within the renders tab of an Assets details page, they are technically stored as attachments on the Asset and are thus accessible via the attachments API as discussed in the downloads section below. In addition to downloading, it is also possible when uploading to indicate that the file should be stored in the renders tab instead of the attachments tab.
To assign an uploaded attachment to the renders tab, in the request body of the sign-url generation endpoint simply set the storeType to RENDER like so:
Then just like the regular attachment process, pull the signed-url from the location parameter of the response and upload the file to this signed-url using a PUT request. As mentioned above, version is optional and only works when parentEntityType is PRODUCT or RENDER.
Downloading Attachments
It is possible to download any attachments that have been uploaded to a Asset, as well as the QR code pertaining to that Asset. This involves using the comments API as they share a storage method and just requires the retrieval of the attachments blobId. As with any Admin API process, you must first properly authenticate.
To retrieve the blobId of your Attachment, you will call the fallowing endpoint:
page: Indicates which page of results to return. 0 indicates the first page.
size: Indicates how many results should be divided amongst each page, 10 means each page will contain up to 10 results.
productUuid: The UUID of the Asset you wish to view the attachments for.
sortDirection: The order you wish the results to be sorted in. ASC means ascending order.
- version: [OPTIONAL] Filters the results by the version at which the attachment was added.
- Only supported for Products, Variant Groups will ignore this field.
There are more parameters that can be passed to narrow down the results. See the full list of endpoints linked above to see these parameters.
This will return a response like the following:
qrCode_some-uuid.png. Using this you can grab its blobId, or the blobId of whatever attachment you wish to download and pass it in the following endpoint: This will return the attachment data and can be saved to a file locally or redirected elsewhere if desired.
Downloading Renders
One key usage of the Attachments API is the storage of an Asset’s renders. Whether auto-rendering is enabled, or you generate renders via the new beta rendering functionality, the generated content can be accessed via Attachments.
Note: While renders are accessible via the Attachments API, they are separated out into a separate Render section of an Asset’s UI which also houses the settings.
blobId to call the /v1/comments/images/{blobId} endpoint. When searching for the correct blobId, there is one key difference, the entityType for renders will be RENDER or TURNTABLE for the images and mp4/gif. Only renders that are actually generated by the Platform will carry the RENDER/TURNTABLE entityType. Any images or videos that are manually uploaded as attachments (or the generated QR code) will carry the normal PRODUCT entityType. Postman Collection
You can test the above methods of downloading Attachments using the linked Postman collection below. The collection covers authentication as well as retrieving an Asset and downloading an Attachment from them. To run it as a collection, simply deselect any endpoints you don’t want to run, and ensure the collections global variables are set in the Pre-request Script of the collection itself. To run the endpoints individually, make sure each endpoints X-AUTH-TOKEN variable is activated in the headers and enter the necessary information to each endpoint. For more information on our Postman collections, visit this guide.