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.
Using the Admin API, you can search for your Assets in order to update them, download their files, or construct their share links/iframes. 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 .
-
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 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.
-
-
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.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
User Role Limitations
There are three endpoints available for searching assets, however your User Role can restrict which of these you can utilize. The below table is not a complete user matrix, but is a simple visual of what roles can make use of which endpoints:
| Role | /v1/products/clients/search | /v1/products/client/{clientUuid}/search | /v1/products/contextual-search |
| Organization Owner | Yes | Yes | Yes |
| Organization Admin | Yes | Yes | Yes |
| Workspace Admin | No | Yes | No |
| Content Manager | No | Yes | No |
| Guest | No | No | No |
/v1/products/client/{clientUuid}/search endpoint as you must specify a workspace you actually have access to. On This Page
Generic Search
There are two endpoints available to search within designated Workspaces, and the requests can be constructed to expect exact or fuzzy results. The endpoints share the same request body structure and response structure, only differing in their URL.
Single Workspace Search
clientUuid of a single Workspace as part of the URL and will only search assets within this Workspace.
POST /v1/products/clients/{clientUuid}/search
The single asset search endpoint shares a lot of parameters with the multi-workspace search endpoint covered below. You can see an example of the single asset search parameters to the right.
Most of the parameters in the request body are optional. The only exceptions are page, size, clientUuids and organizationUuid. Most of the parameters are rather straightforward, however a couple warrant extra explanation and will be expanded upon in the following sections. For a short description of each parameter, see Appendix A below.
Method: POST
Endpoint: /v1/products/clients/{clientUuid}/search
Headers: { x-auth-token: 'Bearer ' + refreshToken }
Body: {
'page' : 1, // Required
'size' : 10, // Required
'organizationUuid' : 'string', // Required
'name' : 'string', // Optional
'searchTerm' : 'string', // Optional
'status' : 'string', // Optional
'tagsUuids' : [ 'string' ], // Optional
'locationsUuids' : [ 'string' ], // Optional
'variantGroupsUuids' : [ 'string' ], // Optional
'conversionStatuses' : [ 'string' ], // Optional
'sorts' : { // Optional
'target' : 'order'
},
'locationName' : 'string', // Optional
'tagName' : 'string', // Optional
'variantGroupName' : 'string', // Optional
'description' : 'string', // Optional
'attrributeKey' : 'string', // Optional
'attributeValue' : 'string', // Optional
'hasAttributes' : boolean, // Optional
'assetTypes' : [ 'string' ], // Optional
'projectsUuids' : [ 'string' ], // Optional
'productsUuids' : [ 'string' ], // Optional
'searchType' : 'string', // Optional
'matchTypes' : { // Optional - See section below for more details
'field' : 'match type'
},
Extended Filter Options : {}, // Optional - See section below for options
}
Multi-Workspace Search
Takes a list of clientUuids and will search across all that are passed. If a clientUuid for a Workspace is passed that you do not have permissions for, a 403 will be returned. Note: this does not apply to users with Workspace level permissions. You will need to use the Single Workspace Search endpoint always.
POST /v2/products/clients/search
The request body is largely the same, as the single asset search request, as well as similar to the v1 of this endpoint, however there are some key differences, some of which will be expanded further below.
- Takes an array of clientUuids to search multiple workspaces.
- searchTerm is now an object used to specify what types of information to limit the search term to.
- attributes is reintroduced to allow an additional type of key-value search for fuzzy searches.
- tagsUuids, locations, and projectsUuids have a ‘NONE’ option now.
- matchAll and integrationsStatus have been newly added.
Method: POST
Endpoint: /v2/products/clients/{clientUuid}/search
Headers: { x-auth-token: 'Bearer ' + refreshToken }
Body: {
'page' : 1, // Required
'size' : 10, // Required
'clientUuids' : [ 'string' ], // Required - Only for the Multi-Workspace Search
'organizationUuid' : 'string', // Optional?
'name' : 'string', // Optional
'searchTerm' : { // Optional
'term' : 'string',
'type' : [ SearchTermEnum ]
},
'status' : 'string', // Optional
'tagsUuids' : [ 'string' ], // Optional
'locationsUuids' : [ 'string' ], // Optional
'variantGroupsUuids' : [ 'string' ], // Optional
'conversionStatuses' : [ 'string' ], // Optional
'sorts' : { // Optional
'target' : 'order'
},
'locationName' : 'string', // Optional
'tagName' : 'string', // Optional
'variantGroupName' : 'string', // Optional
'description' : 'string', // Optional
'attrributeKey' : 'string', // Optional
'attributeValue' : 'string', // Optional
'hasAttributes' : boolean, // Optional
'attributes' : { // Optional
'key' : 'string',
'values' : ['string'],
'equals' : boolean
},
'assetTypes' : [ 'string' ], // Optional
'projectsUuids' : [ 'string' ], // Optional
'productsUuids' : [ 'string' ], // Optional
'matchTypes' : { // Optional - See section below for more details
'field' : 'match type'
},
'matchAll' : boolean, // Optional
'integrationsStatus' : { // Optional
'AMAZON' : [ 'REMOTE_REJECTED', 'REMOTE_FAILED' ]
},
Extended Filter Options : {}, // Optional - See section below for options
}
searchTerm
The searchTerm in the v2 endpoint now expects an object instead of the previous string type. This object will allow you to specify what types of fields the searchTerm should be included in the search. Note: this applies only to fuzzy search, use the more specific search fields with alongside matchTypes to utilize exact search, as explained in later sections.
The type field can take an array of possible values from the following list:
ALL
NAME
UUID
TAG
ATTRIBUTE_KEY
ATTRIBUTE_VALUE
LOCATION
DESCRIPTION
attributes
The attributes field has been updated/reintroduced to allow searching a single attribute key against multiple attribute values.
key– indicates an attribute key to search forvalues– A list of possible attribute values to considerequals– Indicate whether the search should be checking that the asset has (true) or does not have (false) the provided key and values.
tagsUuids, locationsUuids, projectsUuids
These three fields still take a list of strings to search against, however you can now pass a value of “NONE" to specify you want results that do not contain any values for the given field. For example, if you set tagsUuids like the example to the right, the search will only consider assets that no tags assigned to them.
{
...
'tagsUuids' : ["NONE"],
...
}
matchAll
A new parameter, this boolean controls the logic used when combining the various fields you are using to filter the results.
true– parameters are combined using AND logic, so the results must match all provided search parameters.false– parameters are combined using OR logic, so the results may match any of the provided search parameters, but does not need to match them all.
integrationsStatus
Another new parameter, this object allows you to filter results based on their status for a particular integration. At this time, only the Amazon integration exists.
{
...
'AMAZON' : [ 'REMOTE_FAILED', 'REMOTE_REJECTED' ]
...
}
You can pass a list of statuses to check, with the possible values being:
// Amazon Integration Statuses
NOTE_SUBMITTED
REMOTE_PROCESSING
LOCAL_CREATED
REMOTE_CREATED
REMOTE_UPDATED
REMOTE_COMPLETED
REMOTE_REJECTED
LOCAL_ERROR
REMOTE_FAILED
REMOTE_ERROR
Sorts
It is possible to sort the results of the search request before they are returned using a number of different data points on an Asset. The possible sort fields are:
CONVERSION_STATUSWORKSPACE_SLUGTAGSORIGINAL_POLY_COUNTOPTIMIZED_POLY_COUNTORIGINAL_FILE_SIZEOPTIMIZED_FILE_SIZEPIPELINE_NAMECREATEDUPDATEDNAME
Body: {
...
'sorts' : {
'NAME' : 'ASC'
}
}
Generally, asc means starting from the lowest (lowest ORIGINAL_POLY_COUNT, starting from digits 0-9 in an Asset’s NAME), while desc would start from the opposite end. Keep in mind that some of these depend on the data that has been added in order for their results to make sense.
Take TAGS as an example, if you were to sort by ASC order, the results will be determined by the first tag name returned for each Asset, where the tags are sorted first in the same way. Others, like CONVERSION_STATUS work best when paired with another parameter, otherwise it’ll default to sorting the results further by most recently updated.
The sorting happens before the results are returned and are executed individually for ‘groups’, where a group would be some categorization of the Asset such as status, so if your results are expected to return a mix of Assets that are Draft, Live Internal, or Live Public, then the results will group them by these statuses and sort each individually. This means the results may not sort the way you’d expect as all results may be of the Draft status if the number of Draft matches exceeds the number indicated by the size parameter of your search request.
Match Types
There is an object parameter called matchTypes which allows you to identify specific data points on an Asset you would like the search request to match according to, as well as how you would like to match them (exact, fuzzy, etc). There are some specifics about how the possible fields and values for these matchTypes interact that are important to know to ensure your results are as expected, as some combinations will not actually result in any specific behavior (instead acting as if nothing was passed for this parameter).
The possible fields which can be set for matchTypes are:
TAGS_UUIDSSEARCH_TERMNAMEATTRIBUTES_KEYSATTRIBUTES_VALUES
With these, the possible values are:
MATCH_ALLMATCH_ANYMATCH_EXACTMATCH_FUZZY
There are some clear instances where the value wouldn’t make sense with a given field because some of the fields indicate exact data, i.e. passing TAGS_UUIDS : MATCH_FUZZY wouldn’t produce expected results since UUID’s are meant to exactly point to a specific tag, whereas fuzzy search looks for any that are close to exact. See the Proper Pairings below to see what combinations are valid. Note: improper combos won’t produce errors, they just may not produce the results you are looking for, potentially excluding Assets that should be returned.
Body: {
...
'tagsUuids' : [ '03f23fc3-6a78-4e00-95bf-d7d0ed72d9da' ],
'matchTypes' : {
'TAGS_UUIDS' : 'MATCH_ANY'
}
}
TAGS_UUIDS with value MATCH_ANY will filter the results of your search to any Asset which contains one or more Tags as indicated by the tagsUuids parameter of your search request. TAGS_UUIDSMATCH_ALL, MATCH_ANY, MATCH_EXACT(thoughMATCH_EXACTis redundant in this case it will still produce expected results)
SEARCH_TERMMATCH_EXACT, MATCH_FUZZY
NAMEMATCH_EXACT, MATCH_FUZZY
ATTRIBUTES_KEYSMATCH_ALL, MATCH_ANY
ATTRIBUTES_VALUESMATCH_ALL, MATCH_ANY
Extended Filters
One of the optional parameters is shown as Extended Filter Options and is an object. While there are only a couple of different structures involved, they are used by multiple different filters, so they were categorized as Extended Filters for the purposes of this guide.
These filters are:
createdDateRange: date rangeupdatedDateRange: date rangeoriginalFileSizeRange: numeric rangeoptimizedFileSizeRange: numeric rangeoriginalPolyCountRange: numeric rangeoptimizedPolyCountRange: numeric range
Dates
createdDateRange and updatedDateRange refer to the date an Asset was created and last updated, respectively. They are both structured using a startDate and an endDate, formatted in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
Both keys are required, however you do not need to set an actual date for endDate, it can just be set to null if you want to leave it open ended. The above structure applies to both createdDateRange and updatedDateRange.
{
...
'createdDateRange' : {
'startDate' : '2023-07-01T00:00:00',
'endDate' : null
}
}
Asset Metrics
In addition to dates, certain metrics can be used to filter search results by providing a numeric range for their values. These cover the poly count and file size filters above, and involve passing a minValue and a maxValue (though like with endDate, maxValue can be left open ended by passing null)
The file sizes are in bytes.
{
...
'optimizedFileSizeRange' : {
'minValue' : 10000000,
'maxValue' : null
},
'optimizedPolyCountRange' : {
'minValue' : 75000,
'maxValue' : null
}
}
Contextual Search
To put more control into your hands, a contextual search endpoint has been added which allows for the passing of a query string based on ElasticSearch rules, with some limitations for performance and security reasons.
This will search across the entire Organization, unless a list of specific clientUuid’s are passed. The page and size parameters indicate pagination in the results, with page indicating which page of results you wish to see, and size indicating how many results per page there should be. The rest of the parameters require a little more information.
Method: POST
Endpoint: /v1/products/contextual-search
Headers: { 'x-auth-token' : 'Bearer ' + refreshToken }
Body: {
'page' : 1, // Required
'size' : 10, // Required
'query' : 'furniture', // Required
'clientsUuids' : [], // Optional
'fields' : [], // Optional
'sortField' : '', // Optional
'sortOrder' : '' // Optional
}
Query Capabilities
The query parameter can take in a string argument with the following features:
Searching across all indexed Asset data.
Searching within a specific attribute.
This does not refer to ‘attributes’ as they exist on the VNTANA Platform, but an attribute of the Asset’s data, i.e. you can specify the query should check Asset descriptions that contain a keyword a la
description:furniture.See Appendix () – Allowed Search Fields for the full list of attributes you can search for.
Logical Operators
AND, OR, NOT.Example: jewelry AND furnitureTrailing Wildcards:
test*Wildcards at the beginning of a word are disabled (
e.g. *ing).
Relational Operators
>, <, >=, <=.Search for phrases:
Example: "\"this is a cat\""Precedence:
Example: (fruits OR vegetables) and (NOT avocado)Ranges:
Example: created:[2024-08-01 TO 2024-08-23Exists keyword:
Example: _exists_:projects
See Appendix B for the full list of query fields.
Fields
When using a term or value in the query, it is possible to limit the attributes it applies to by passing the attribute in either the query itself, as shown in the example above description:furniture. However, it is also possible to pass a list of attributes via the fields parameter. This allows for a simpler means of multi-attribute searches while keeping the query simple.
The same options that can be included in the query can be passed as fields values. See Appendix B for the full list of allowed search fields.
{
...
'query' : 'chair',
'fields' : ['name']
}
Field vs Query
fields parameter or as part of the query parameter. Due to some limitations for performance and security reasons, as well as the nature of certain fields, there are cases where relying on the fields parameter will not produce the results you expect. When using relational operators (<, >, etc.) in your query, the field you wish to apply the relational operator must be included in the query, not the fields parameter.
{
...
'query' : '<10000',
'fields': [ 'asset.assetOrigionalSize' ]
}
will not work, instead use
{
...
'query' : 'asset.assetOriginalSize:<10000',
'fields' : []
}
Additionally, some queryable values must be accompanied by their query field due to how ElasticSearch parses the query. In these cases leaving the query field out of the query itself can inadvertently create an entirely different query.
{
...
'query' : '4ba64907-f9f4-41e2-8d1e-415650b3c1e1',
'fields' : [ 'uuid' ]
}
Any uuid query will be parsed incorrectly without the query field included as the ‘-‘ will be treated as a special character and not a part of the value otherwise. Instead, we can add uuid to the query like below:
{
...
'query' : 'uuid:4ba64907-f9f4-41e2-8d1e-415650b3c1e1'
}
uuid of some sort. Sorts
The final two optional parameters are used together to apply a sort order based on a single attribute. The first, sortField allows you to pass one of the allowed search fields to sort by, and the second sortOrder allows you to identify the order the results should be sorted in.
sortOrder only has two options: asc and desc where desc means the sorted results start from the newest / lowest / closest match, while asc starts from the opposite end. Keep in mind that with the variety of sort fields available what asc means isn’t always the same.
{
...
'sortField' : 'created',
'sortOrder' : 'asc' or 'desc'
}
Appendix
A - Regular Search Parameter Descriptions
| Parameter | Required | Type | Description |
| page | Required | int | Indicates which page of the paginated results should be returned. Works in tandem with size. |
| size | Required | int | Indicates how many results should be included in each page when paginated. Works in tandem with page. |
| clientUuids | Required* | list:str | Only for the mult-workspace endpoint, indicates a list of workspaces the search should limit itself to. Leave empty to search the entire organization. |
| organizationUuid | Required | str | Indicates the Organization that should be searched. |
| name | Optional | str | A value to compare Asset names across when filtering results. Can be used with matchTypes to indicate exact or fuzzy search method. |
| searchTerm | Optional | str | A generic value to compare Assets across when filtering results. Will try to find some metadata about an Asset that matches this value. Can be used with matchTypes to indicate exact or fuzzy search method. |
| status | Optional | list:str | A list of publish statuses for the Assets you'd like to filter for. Values can be WAITING_REVIEW, APPROVED, REJECTED, LIVE_INTERNAL, LIVE_PUBLIC, DRAFT. Can be an empty list or left out entirely. |
| tagsUuids | Optional | list:str | A list of tag UUIDs to check Assets for when filtering results. Can be used with matchTypes to indicate whether you'd like only results that match ALL tagUuids or just match ANY tagUuids. |
| tagName | Optional | str | A value to compare Asset tags against using the tag's name. |
| locationsUuids | Optional | list:str | A list of location UUIDs to check Assets for when filtering results. |
| locationName | Optional | str | A value to compare Asset location names against using the location's value. |
| variantGroupsUuids | Optional | list:str | A list of Variant Group UUIDs to check Assets for when filtering results. |
| variantGroupName | Optional | str | A value to compare Asset Variant Group names against using the name of a Variant Group. |
| conversionStatuses | Optional | list:str | A list of conversion statuses to filter results by. Values can be PENDING, CONVERTING, COMPLETED, FAILED, NO_ASSET, TERMINATED. |
| sorts | Optional | Object | An object taking a key:value pair to sort the results by such as name in ascending order. |
| description | Optional | str | A value to check Asset descriptions against. |
| attributesKeys | Optional | list:str | A list of values to check an Asset's attribute keys against. Can be used with matchTypes to indicate whether ALL or ANY of the keys should be found on the Asset. |
| attributesValues | Optional | list:str | A list of values to check an Asset's attribute values against. Can be used with matchTypes to indicate whether ALL or ANY of the keys should be found on the Asset. |
| hasAttributes | Optional | bool | A boolean indicating whether you want to outright filter out any Asset that does not have any Attributes. |
| assetTypes | Optional | list:str | A list of values to check an Asset's type against. Values can be THREE_D, IMAGE, VIDEO, DOCUMENT, PROJECT, MATERIAL, AUDIO, NATIVE, TRIM, AVATAR, NO_ASSET. |
| projectsUuids | Optional | list:str | A list of Project UUIDs to check Assets for when filtering results. |
| matchTypes | Optional | Object | An object taking a key:value pair to indicate how another search parameter should be considered. Influences whether results are fuzzy or exact depending on the chosen keys. |
| createdDateRange | Optional | Object | An object taking a date range. Filters results based on those whose creation date lines up with the indicated range. |
| updatedDateRange | Optional | Object | An object taking a date range. Filters results based on those that were last updated within the indicated range. |
| originalFileSizeRange | Optional | Object | An object taking a file size range. Filters results based on those that have an original file size within the indicated range. If not omitted, it will filter the results by omitting any Asset that doesn't have an original file. Only include intending to use. |
| optimizedFileSizeRange | Optional | Object | An object taking a file size range. Filters results based on those that have an optimized fle size within the indicated range. If not omitted, it will filter results by omitting any Asset that doesn't have an optimized format, including all non-3D types. Only include if intending to use. |
| originalPolyCountRange | Optional | Object | An object taking a numeric range. Filters results based on those whose original Asset has a poly count within the indicated range. If not omitted, it will filter the results by omitting any Asset that doesn't have an original file. Only include intending to use. |
| optimizedPolyCountRange | Optional | Object | An object taking a numeric range. Filters results based on those whose optimized Asset has a poly count within the indicated range. If not omitted, it will filter results by omitting any Asset that doesn't have an optimized format, including all non-3D types. Only include if intending to use. |
B - Contextual Search Allowed Search Fields
uuid
name
clientUuid
clientSlug
description
created
updated
assetType
conversionStatus
pipelineUuid
pipelineName
tags.name
tags.uuid
attributes.key
attributes.value
asset.assetOriginalSize
asset.assetOriginalName
asset.conversionFormats
asset.generationRequestUuid
asset.assetBlobId
asset.thumbnailBlobId
asset.models.modelSize
asset.models.modelBlobId
C - Postman Collections
The provided Postman collection includes all the endpoints necessary to navigate the proper Authentication flow, as well as test out each of the three search endpoints discussed in this guide. The collection is not expected to work out of the box as you will need to enter in relevant information both for authentication and how you want to format the search requests themselves.
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.