API – Retrieving Project Data

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 folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.

There are three methods of retrieving Project data. To begin, Projects can be searched using a variety of filters, similarly to the functionality of searching for Assets. There are two methods that can be utilized to search for Projects. Additionally, you can make a direct request for a Projects data if you know its UUID beforehand.

Publish Status For all three methods contained in this guide, only Projects which are in a Live Internal or Live Public state will be retrievable via the API.

As with all Admin API processes you must first authenticate. View our Authentication guide for a detailed explanation of the steps involved, or use the below summary to authenticate.

Authentication Steps Summary

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.
  
  1
  
  2
  
  3
  
  4
  
  {
  
  ‘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.
  
  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.

Filter By Workspace

The first method will allow you to search for Projects within a single Workspace by passing its clientUuid, as well as allow direct filtering via tagsUuids and locationsUuids. To perform this search, use the following request:

Method: POST
Endpoint: /v1/projects/filter-parents-by-client
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“page”: 1,
“size”: 10,
“clientUuid”: “string”,
“statuses”: [
“LIVE_INTERNAL”,
“LIVE_PUBLIC”
],
“tagsUuids”: [
“string”
],
“locationsUuids”: [
“string”
],
“sortDirection”: “ASC”,
“sortField”: “CREATED”
}

page: [REQUIRED] Indicates the page of results to return. Minimum accepted value is 1, which simply returns the first page of results.
size: [REQUIRED] Indicates how the results should be paginated. A size of 10 indicates that each page will contain 10 results, so page:1 and size:10 will return the first 10 results found.
clientUuid: [REQUIRED] The UUID of the Workspace you wish to search.
statuses: [OPTIONAL] Allows the filtering of results by their publish statuses. Only Live Internal and Live Public Assets can be returned.
tagsUuids: [OPTIONAL] A list of tagUuid’s to filter the Projects by. Only Projects which contain one or more of the included UUID’s will be included in the results.
locationsUuids: [OPTIONAL] A list of locationUuid’s to filter the results by. Only Projects which contain one or more of the included UUID’s will be included in the results.
sortDirection: [REQUIRED] Indicates the order the results should be returned in. Can be ASC or DESC, with ASC referring to oldest to newest.
sortField: [REQUIRED] Indicates what parameter to sort by. Can be the date CREATED or UPDATED.

A successful response will return the results in the following format:

{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “”,
“clientUuid”: “”,
“name”: “Postman Test”,
“description”: “”,
“thumbnailUuid”: null,
“status”: “LIVE_INTERNAL”,
“locations”: [],
“tags”: [],
“attributes”: {},
“productsUuids”: [
“string”,
“string”,
“string”
],
“parentUuid”: null,
“subProjects”: null,
“created”: “2023-11-01T23:32:26.28”,
“updated”: “2023-11-04T19:32:31.286”
}
]
}
}

As mentioned above, only Projects in Live Internal or Live Public state will be returned, and similarly in the response, only linked Assets that are published to a Live state will have their productUuid returned.

Search Multiple Workspaces

The second method of search allows you to search multiple Workspaces by taking in a list of clientUuids. This endpoint is more generalized in nature, substituting the search parameters for tags and locations to a more generalized searchTerm parameter. To perform this search, use the following request:

Method: POST
Endpoint: /v1/projects/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“page”: 1,
“size”: 10,
“clientUuids”: [
“string”
],
“parentUuid”: “string” or null,
“searchTerm”: “string” or ”,
“includeProductsSearch”: true or false,
“sorts”: {
“CREATED” or “UPDATED” : “ASC” or “DESC”
}
}

page: [REQUIRED] Indicates the page of results to return. Minimum accepted value is 1, which simply returns the first page of results.
size: [REQUIRED] Indicates how the results should be paginated. A size of 10 indicates that each page will contain 10 results, so page:1 and size:10 will return the first 10 results found.
clientUuids: [REQUIRED] A list of clientUuid’s to apply the search to. Must include at least one clientUuid.
parentUuid: [OPTIONAL] Indicates the UUID of a Parent Project to limit the search to.
searchTerm: [OPTIONAL] Acts as a means to filter the results. This can be the text of a tag, attribute key, or part of the name or description.
includeProductsSearch: [REQUIRED] Indicates whether to include linked Assets when checking the searchTerm.
sorts: [OPTIONAL] An object indicating a method to sort the results by. Options are by date Created or Updated and sorted in Ascending or Descending order. Note: Ascending would refer to oldest to newest.

A successful request will return the results in the following format:

{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“clientUuid”: “string”,
“clientSlug”: “dam-testing”,
“name”: “Postman Test”,
“description”: “”,
“parent”: null,
“tags”: [],
“locations”: [],
“productsUuids”: [],
“status”: “LIVE_PUBLIC”,
“created”: “2023-11-08T21:40:20.681”,
“updated”: “2023-11-08T22:27:46.34177”,
“attributes”: [],
“subProjects”: null
}
]
}
}

As with single Workspace searches, only Projects in Live Internal or Live Public state will be returned, and similarly in the response, only linked Assets that are published to a Live state will have their productUuid returned.

Get Project By UUID

In addition to searching for Projects with various search criteria, the data of a Project can be directly fetched using another endpoint so long as the UUID of the Project is known. To retrieve the Project’s data, call the following endpoint:

Method: GET
Endpoint: /v1/projects/{{ uuid }}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshtToken }

A successful response will look like the following:

{
“success”: true,
“errors”: [],
“response”: {
“uuid”: “string”,
“clientUuid”: “string”,
“name”: “Postman Test”,
“description”: “Testing retrieving an Asset with Postman”,
“thumbnailUuid”: null,
“status”: “LIVE_INTERNAL”,
“locations”: [],
“tags”: [],
“attributes”: {},
“productsUuids”: [],
“products”: [],
“parentUuid”: null,
“subProjects”: null,
“created”: “2023-11-03T01:15:56.525”,
“updated”: “2023-11-07T02:40:29.821”
}
}

Unlike with Asset search options, there is no difference in the result of the direct UUID retrieval and the generic searches for Projects (except in the case of clientSlug in the multi-Workspace response). This just allows a simpler and faster result if you already have the projectUuid on hand.

Unique Errors

PROJECT_IS_NOT_PUBLISHED

Returned if the projectUuid passed corresponds to a Project that is in DRAFT.

Important: as with the search endpoints, only Live Internal or Live Public Projects will be accessible, and only info relating to Assets that are in a Live state will be returned.

Postman Collections

You can test the above endpoints with the following Postman collection. This collection contains each of the 3 types of Project data retrieval, as well as each of the Authentication steps. To run the collection as a whole, you will need to deselect the endpoints you do not need or want to run, and ensure the global variables are set in the collections Pre-request Script.

If you would like to run the endpoints individually you must re-enable the X-AUTH-TOKEN header for all endpoints except the login endpoints, and ensure each endpoint has the necessary body and query parameters.

Resources