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 manage the versions for your Assets by creating new versions, updating existing versions, and changing which version is the ‘current’ version. Additionally, it is possible to search for the versions of an Asset via the API in order to see the various settings and metadata associated with them. In order to interact with versions via the API, proper authentication is needed, 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.
On This Page
Creating a New Version
This endpoint serves to enable directly creating a new version either for review or to set as ‘Current’, while providing control over the ‘original’ asset and optimization settings associated with the version. This endpoint does not provide the ability to overwrite the ‘current’ version, only create a new one and set it to ‘current’.
The endpoint is very similar to the Asset creation endpoint with a couple additional fields in the request body:
productUuid: Indicates which Asset the version is to be made from.saveOption: Indicates the version save strategy.NEW_AS_CURRENT– Creates a new version and immediately sets it as the current version.NEW_FOR_REVIEW– Creates a new version for QA, current version remains current.
keepOriginalFile: Indicates whether the original file should be retained.Defaults to true, set it to false if you intend to upload a new file for the version, otherwise a value of true will simply copy the file from the current version and trigger optimization (if optimization settings are being changed in this new version)
versionSource: An optional parameter that allows you to set the version number that the new version will copy from.- Omitting this field will have the new version copy from the current version.
Method: POST
Endpoint: /v1/products/versions
Headers: { 'x-auth-token': 'Bearer ' + refreshToken }
Body: {
'productUuid': 'string', // Required
'clientUuid': 'string', // Required
'saveOption': 'string', // Required
'keepOriginalFile': true, // Optional - default true
'versionSource': 1, // Optional
// Additional fields match /v1/products endpoint
}
See the guide on Creating Assets for additional request fields. The additional fields are optional, anything not included will just be copied from the version that the new version get’s generated from.
A successful creation will return a response consisting of:
uuid– The version uuid, not the asset uuid.version– The version number of the new version.name– The name of the version.
{
"success": true,
"errors": [],
"response": {
"version": 1,
"uuid": "01a9c65b-c77b-472b-8559-5c13f673ece0",
"name": "New Version"
}
}
Possible Errors
- MISSING_PRODUCT_UUID,
- PRODUCT_NOT_FOUND,
- MISSING_SAVE_OPTION,
- INVALID_SAVE_OPTION
- INVALID_VERSION
- PRESET_NOT_FOUND
- INVALID_TAG_UUID – One or more values in tagsUuids is blank
- TAG_NOT_FOUND
- LOCATION_NOT_FOUND
- INVALID_LOCATION_UUID – One or more values in locationsUuids is blank
- INVALID_ATTRIBUTE_KEY – One or more attribute keys fails the key validation check
- MISSING_ATTRIBUTE_VALUE – One or more attribute values is blank
- VIEWER_SETTINGS_NOT_FOUND
- INVALID_VIEWER_SETTINGS_CONFIG
- ATTRIBUTE_KEY_EXCEEDS_ALLOWED_LIMIT
- INVALID_MODEL_OPS_PARAMETERS
- MAX_VERSIONS_EXCEEDED
- VERSION_CREATION_IS_UNAVAILABLE – The product’s asset is currently being processed (non-terminated conversion or malware scan in progress)
Updating a Version
Missing from the previous endpoint is the option to overwrite the current version. This is the option which matches the behavior VNTANA has had up to the release of Versions and is still the default behavior of the Creation/Update Asset endpoints in the absence of the new versionSaveOption. In addition to this field being added to those endpoints, there is a new endpoint for the updating of a version which allows all three version save strategies: creating a new version for QA, creating a new version and setting to ‘current’, and overwriting the ‘current’ version.
Like the version creation endpoint, we have productUuid, saveOption, and keepOriginalFile. One slight difference is with saveOption:
saveOptionsupportsNEW_AS_CURRENT,NEW_FOR_REVIEW, andOVERWRITE.OVERWRITEwill simply overwrite the existing ‘current’ version.
Additionally, version is the version number you wish to OVERWRITE, it can be left out if you are using NEW_AS_CURRENT or NEW_FOR_REVIEW in which case it will base the ‘copy’ off the current version. otherwise, it indicates which version to copy from.
As with the creation endpoint, the response will provide the new versions # in the body.
Method: 'PUT'
Endpoint: /v1/products/versions
Headers: { 'x-auth-token' : 'Bearer ' + refreshToken }
Body: {
'productUuid': 'string',
'clientUuid': 'string',
'version': int,
'saveOption': 'string',
'keepOriginalFile': true,
// Additional fields from Update Asset endpoint /v1/products
}
See the guide on Updating Assets for additional request fields.
Possible Errors
- PRODUCT_NOT_FOUND,
- VERSION_NOT_FOUND,
- MISSING_PRODUCT_UUID,
- MISSING_VERSION_UUID,
- MISSING_SAVE_OPTION
Searching an Asset's Versions
When calling the standard Asset search endpoints, you will only retrieve the version number for the ‘current’ version of each Asset. In order to see the list of versions available for a specific Asset, you will need to utilize a new endpoint on an Asset by Asset basis.
This will return a response similar to the Asset search endpoint, but the entries within the grid are versions of the indicated Asset. You will also receive the totalCount which will provide the total number of versions for the productUuid, however bear in mind that this number doesn’t necessarily reflect the highest Version # available. If an asset has 6 versions, and say Version 2 is deleted, the totalCount would reflect 5 versions because version 2 was removed, but the remaining versions retain their version number, so version 6 would still be the highest version #.
Method: POST
Endpoint: /v1/products/versions/search
Headers: { 'x-auth-token' : 'Bearer ' + refreshToken }
Body: {
'productUuid': 'string',
'page': 1,
'size': 10
}
The version related details to keep in mind are:
version– Indicates the version number as an int.lastUpdatedBy– Indicates the user that last updated the version.current– Indicates whether this version is set as the ‘current’ version.
Possible Errors
- PRODUCT_NOT_FOUND – provided productUuid doesn’t match existing asset.
- MISSING_PRODUCT_UUID – productUuid was not provided in request.
- INVALID_PAGE – requested an invalid page number for available possible results with size considered.
- INVALID_SIZE – request invalid size (not an int or <=0)
Retrieving an Asset's Versions by UUID
In addition to the search endpoint, you can retrieve a full list of all versions (as opposed to a paginated list) for an Asset using it’s UUID.
In this request, you can add an optional query parameter pageSize which takes an integer. This has the same meaning as the size parameter on the search endpoints, however the response will not actually be paginated. Instead, what it does is paginate the results on the backend and return the pageNumber that the version would appear on if you were to do a paginated version request.
The response includes the same version related fields as the standard search endpoint.
Method: GET
Endpoint: /v1/products/versions/{productUuid}?pageSize=10
Query Params: pageSize [int] Indicates number of versions
per page, does not actually paginate the response
Headers: { 'x-auth-token': 'Bearer ' + refreshToken }
Possible Errors
- PRODUCT_NOT_FOUND – provided productUuid doesn’t match existing asset.
Retrieving a Version
Finally, it is also possible to retrieve a specific versions details using the version number and Asset UUID.
This will return a response similar to the regular asset retrieval request, but with four additional fields:
- version: the version number requested.
- lastUpdatedBy: the user who last updated this version.
- current: indicates whether this version is the current version.
Method: GET
Endpoint: /v1/products/versions/{productUuid}/{version}
Headers: { 'x-auth-token': 'Bearer ' + refreshToken }
Possible Errors
- PRODUCT_NOT_FOUND – provided productUuid doesn’t match existing asset.
- VERSION_NOT_FOUND – provided version doesn’t match an existing version.
Set Version as Current
One of the reasons for retrieving the versions for an Asset is to be able to know what versions are available to set as the current version. With the version number in hand, it is simple to set it to current using the endpoint /v1/products/versions/current.
Method: POST
Endpoint: /v1/products/versions/current
Headers: { 'x-auth-token' : 'Bearer ' + refreshToken }
Body: {
'productUuid': 'string', // Required - the uuid of the Asset
'version': 1 // Required - the version number
}
Upon a successful operation, it will return a response that contains the field uuid. This is the version UUID, not the Asset’s UUID.
{
"success": true,
"errors": [],
"response": {
"uuid": "88888888-0000-0000-0000-000000000008"
}
}
Possible Error Codes
- PRODUCT_NOT_FOUND – provided productUuid is invalid.
- VERSION_NOT_FOUND – provided version number doesn’t exist.
- MISSING_PRODUCT_UUID – the productUuid was not included in the request.
- MISSING_VERSION – version was not included in the request.
- INVALID_VERSION – version isn’t a valid version number.
Reconvert a Version
Another use case for the information retrieved from the version search endpoints is to reconvert or re-optimize certain versions. Note: this endpoint doesn’t permit the changing of optimization settings or pipeline, for that use the regular version update endpoint.
The endpoint to reconvert has a couple of different means by which it can be utilized, differing by whether you choose to use the version specific UUIDs or the version number.
Method: 'PUT'
Endpoint: /v1/products/versions/reconvert
Headers: { 'x-auth-token' : 'Bearer ' + refreshToken }
Body: {
'productUuid': 'string', // Required
'uuid': 'string', // Optional
'version': 1, // Optional
}
Upon a successful operation, it will return a response that contains the field uuid. This is the version UUID, not the Asset’s UUID.
{
"success": true,
"errors": [],
"response": {
"uuid": "88888888-0000-0000-0000-000000000008"
}
}
Possible Error Codes
- PRODUCT_NOT_FOUND – provided productUuid is invalid.
- VERSION_NOT_FOUND – provided version number doesn’t exist.
- MISSING_PRODUCT_UUID – the productUuid was not included in the request.
- MISSING_VERSION – version was not included in the request.
- INVALID_VERSION – version isn’t a valid version number.
Delete Non-Current Versions
It is also possible to delete one or all non-current versions via the API with a single API call. To do so you can pass the productUuid of the Asset plus an array of the specific versions UUIDs that you wish to delete. The version UUIDs can be retrieved via the Version search endpoints above.
If the uuids field is passed as an empty list or not passed at all, the endpoint will treat this as requesting all non-current versions be deleted.
Method: DELETE
Endpoint: /v1/products/versions
Headers: { 'x-auth-token': 'Bearer ' + refreshToken }
Body: {
'productUuid': 'string', // Required - Asset's UUID
'uuids': ['string'] // Optional - Version UUIDs
}
A successful response will simply return the number of versions deleted.
{
'success': True,
'errors': [],
'response': {
'count': 1,
'errors': None
}
}
Possible Errors
- PRODUCT_NOT_FOUND – the productUuid provided doesn’t match an existing Asset.
- MISSING_PRODUCT_UUID – productUuid wasn’t included in request.
- MISSING_UUIDS – while the list can be empty, it is still necessary to pass the field with at least an empty array.
- DELETE_CURRENT_NOT_ALLOWED – attempted to delete the current version which can only be deleted using the Asset delete endpoint.
Postman Collection
The above endpoints can be tested with the Postman collection linked below. This collection includes authentication endpoints as well as globals to set for authentication and the Asset you wish to test with within the collections pre-script. For more info on using the Postman collection, check this guide.