Resources

API – Upload Attachments

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

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 Configurator or a Comment then you will have to first upload the attachment to the Workspace and then add to the Configurator or Entity. This guide will show the process of uploading an attachment to an Asset and a Configurator.

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.

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

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

      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.

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:

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”
}
]
}
}

Now that you have a Workspace UUID you are ready to upload the Attachment.

Uploading Attachment to an Asset

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.

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:

1
2
3
4
5
6
7
8
9
10
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:

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

With the necessary information, you can use the following endpoint to upload your Attachment.

1
2
3
4
5
Method: POST
URL: /v1/attachments/upload/product-attachment
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘clientUuid’, ‘productUuid’
Form Data: fileToUpload
An example URL for this endpoint will look like this: https://api-platform.vntana.com/v1/attachments/upload/product-attachment?clientUuid=some-client-uuid&productUuid=some-prod-uuid. A successful upload will return the following:
1
2
3
4
5
6
7
8
9
{
“errors”: [],
“response”: {
“blobId” : “string”,
“blobSize” : 0,
“metaData” : {}
},
“success” : true
}

Uploading Attachment to Configurator

Adding an Attachment to anything else is a little more involved. In order to add an Attachment to a Configurator, you must first upload the file to the Workspace the Entity exists in. Using the Workspace UUID obtained above, you can use the following endpoint to upload the file:

1
2
3
4
5
Method: POST
URL: /v1/attachments/upload
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘clientUuid’
Form Data: File to upload

A successful response will return the following data:

1
2
3
4
5
6
7
8
9
{
“errors” : [],
“response” : {
“blobId” : “string”,
“blobSize” : 0,
“metaData” : {}
},
“success” : true
}

The key value returned here is blobId which will be used in subsequent methods to add the Attachment to a Configurator. To add the attachment to a Configurator, you will need the Configurators UUID. You can view our Configurator guide to get a detailed look at searching for Configurators, or use the following sample:

The Request is structured as follows:

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
Method: POST
URL: /v1/variant-groups/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“clientUuids”: [
“string”
],
“description”: “string”,
“name”: “string”,
“organizationUuid”: “string”,
“page”: 1,
“productName”: “string”,
“productsUuids”: [
“string”
],
“searchTerm”: “string”,
“size”: 1,
“sorts”: {
“additionalProp1”: “string”,
“additionalProp2”: “string”,
“additionalProp3”: “string”
},
“status”: [
“DRAFT”
],
“tagName”: “string”,
“tagsUuids”: [
“string”
]
}

The Response is structured as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
“response”: {
“grid”: [
{
“clientUuid”: “string”,
“name”: “string”,
“productsCount”: 0,
“tags”: [
{
“name”: “string”,
“uuid”: “string”
}
],
“updated”: “2022-06-29T16:42:10.102Z”,
“uuid”: “string”
}
],
“totalCount”: 0
},
“success”: true
}

You can use the name in the response to pinpoint the correct Configurator.

To then upload the attachment to the Configurator you can use the following endpoint.

1
2
3
4
Method: POST
URL: /v1/attachments/variant-group
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken}
Query Params: ‘blobId’, ‘name’, ‘variantGroupUuid’

This will return the attachment’s UUID upon successful upload.

Attachments can also be added to Comments, Annotations, and Hotspots. These will follow a similar process as adding to a Configurator, needing to add the attachment to the Client / Folder then finding the entityUuid of the Comment, Annotation, etc to add the attachments blobId to.

Postman Collection

You can test the above methods of uploading Attachments using the linked Postman collection below. The collection covers authentication as well as retrieving a Configurator or Asset and uploading an Attachment to 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.

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.