Resources

API – Searching for Assets

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.

Using the Admin API, you can search for your Assets that are in the Live Internal or Live Public state in order to update them, download their files, or construct their share links/iframes. Draft Assets will not be returned by search endpoints. The VNTANA Platform offers a variety of parameters for the Assets you create which allow for these Assets to be retrieved via searches both on the Platform and via the API. These parameters include but are not limited to Attributes, Tags, and Conversion Status.

When searching via the API, the process is the same with the only difference being the parameters passed in the Request Body. Before making a request to the Asset Search endpoint, you must be properly authenticated. View this guide to see a more detailed explanation of the steps required to authenticate .

  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, there are a couple of endpoints that can be used. Depending on your access level, you may be required to use one over the other.

If you have Organization Owner / Organization Admin level access, you can use the following endpoint:

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’
}

While Organization level users can also use the following endpoint, if you only have Folder level access (Workspace Admin or Content Manager) you must use the following endpoint:

1
2
3
4
5
6
7
8
9
10
Method: POST
Endpoint: /v1/products/client/{clientUuid}/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
‘page’ : 1,
‘size’ : 10,
‘searchTerm’ : ‘string’,
‘name’ : ‘string’,
‘organizationUuid’ : ‘string’
}

Note: this search endpoint does not take clientUuids in the Request Body like the previous endpoint, instead passing a single clientUuid in the URL of the request. This of course means this endpoint will only be able to search a single Workspace, while the previous endpoint can search multiple.

All searches made on the VNTANA Platform and via the API use a fuzzy search concept. This means that the results returned are sorted by relevance, with the most relevant results being returned first. The parameters page and size are required parameters which indicate how to paginate the results, meaning

1
2
3
4
{
‘page’ : 1,
‘size’ : 10
}

will return the first page of results at 10 products per page. From here the other search parameters can be used to filter or sort the results.

Important: Assets which are in the Draft state on the Platform will not be returned from search endpoints. They must be in either the Live Internal or Live Public state.

The full possible Request Body for Asset search is as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
“attributeKey” : “”,
“attributeValue” : “”,
“clientUuids” : [],
“conversionStatuses” : “string”,
“description” : “”,
“locationName” : “”,
“locationsUuids” : [],
“name” : “”,
“organizationUuid” : “”,
“page” : 1,
“size” : 10,
“searchTerm” : “”,
“sorts” : {},
“status” : [“LIVE_INTERNAL”, “LIVE_PUBLIC”],
“tagName” : “”,
“tagsUuids” : [],
“variantGroupName” : “”,
“variantGroupUuids” : []
}
Important: These are the same for both search endpoints with the exception that the single client search does not take a parameter clientUuids in the request body.

Search Assets by Attribute

One parameter which can be used to sort the results of a search are Attributes. Attributes are directly tied to the Asset for which they are applied. Multiple Assets can have the same Attribute key and value pair, but a single Asset can only have the same Attribute key once.

There are a couple key notes to keep in mind with this search method. Only one Attribute can be used per search request, and if the Attribute key or value have a space in them it will not work. These issues can be partially circumvented by making use of the searchTerm parameter, multiple terms can be included into this separated by spaces and it will attempt to find assets which match as many of the words in any way possible. The Attribute search parameter is slated to be updated to remove the existing restrictions.

1
2
3
4
5
6
7
{
‘attributeKey’ : ‘string’,
‘attributeValue’ : ‘string’,
‘clientUuids’ : [],
‘page’ : 1,
‘size’ : 100
}

Search Assets by Tags

Tags can also be used to filter the results of a search. Unlike Attributes which are directly tied to the Assets they are applied to, Tags are actually tied to the Workspace in which they are created. Multiple Workspaces can have the same Tag, but they are unique Tags with separate UUID’s meaning when searching for a Tag, unless you are searching all Workspaces that could contain that Tag Name, you will not see the all possible results. Unless you only wish to check a single Workspace, it is best practice when looking for specific Tags to simply search the entire Organization.

Tag UUID's

When searching by Tag UUID’s you will have to pass along a list of all Tag UUID’s you wish to include.

1
2
3
4
5
6
{
‘clientUuids’ : [],
‘page’ : 1,
‘size’ : 100,
‘tagsUuids’ : [ ‘some-tag-1’, ‘some-tag-2’ ]
}

These UUID’s can either be stored locally, or you can retrieve a list of Tags and use the UUID’s you retrieve in your Asset search request.

To retrieve a list of Tags use the following endpoint:
1
2
3
4
5
6
7
8
9
Method: POST
Endpoint: /v1/tags/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘clientUuid’ : ‘some-client-uuid’,
‘page’ : 1,
‘size’ : 10,
‘searchTerm’ : ‘string’
}
The UUID’s of the Tag(s) you wish to utilize can be pulled from the response, structured as such:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 2,
“grid”: [
{
“uuid”: “some-tag-uuid-1”,
“name”: “Some Tag 1”
},
{
“uuid”: “some-tag-uuid-2”,
“name”: “Some Tag 2”
}
]
}
}

When searching with Tag UUID’s, only assets that contain at least one of the included Tags will be returned, with the results being sorted based on any other criteria you may include.

Tag Names

Searching by Tag Name is more limited than searching by Tag UUID, but does not require the additional step of retrieving these UUID’s (if not already known). The tagName can take multiple terms separated with a space, and like with Attributes, you can add more by adding Tags to the searchTerm parameter. In addition to not needing the UUID’s already, with this method you can get more results as the search will return Assets that are deemed relevant, even if the tagName doesn’t completely match a certain Asset’s Tag name.

Search Assets by Conversion Status

Another useful Asset parameter to search by is conversionStatus. This refers to the Conversion Status of a 3D Asset, or where in the Optimization process the Asset is. This can be used to check when a newly created asset has completed its conversion or simply automating the process of retrieving Assets as they finish converting after uploading in bulk. Generally we would recommend using our Webhook’s to subscribe to Asset Conversion events to be automatically notified when this happens, but if a Webhook’s solution doesn’t work for your integration, then you can simply make the Search API calls. You can view the Webhook’s guide here.

A list of the Conversion Statuses that can be retrieved and their Webhook Event equivalent for reference.
Processing Status API Response Webhook Event
Uploading NO_ASSET product.added
Pending PENDING product.pending
Processing CONVERTING product.processing
Completed COMPLETED product.complete
Terminated TERMINATED product.terminated
Failed FAILED product.failed

Postman Collections

Below are a couple Postman collections for testing Asset searches.

The Search Product collection is a general purpose search collection, for you to enter the various search Parameters allowed for the endpoint.

The Search Product by Tag UUID’s collection is specifically used for searching by Tag UUID’s which requires an extra endpoint. Of course, you could have these UUID’s stored locally and skip that step, but incase you do not, this will show you how to handle it.

You can view a guide on using our Postman collections here but generally you can either enter the necessary global variables for the whole collection and run the collection as a whole (need to choose which type of authentication to use, key or email / pass) or run each individually and enter the data as needed. To run them separately, you’ll need to activate the deactivated headers for each endpoint.

Search Product Collection

Search Product by Tag UUID’s Collection

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.