API – Project Creation / Updating

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.

In addition to Workspaces, the VNTANA Platform offers another form of Asset management via the usage of Projects. A Project is similar to a directory in that you can link your Assets to a Project to organize them, and any Project can contain sub-Projects also containing Assets. Like Assets, the creation and handling of Projects is possible via the API.

Note: Projects and Sub-Projects can be created at the same time as the creation of an Asset by passing necessary information into the /v1/products request. For more information view the guide on Creating and Updating Assets.

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.

Project Creation

Projects contain a lot of the same information already accessible to Assets. They can be give a description, assigned tags, attributes and locations, as well as live in different publish states. As such, the Project creation endpoint will look quite similar the Asset Creation/Update endpoint, but with some noticeable difference such as the lack of the modelOpsParameters for optimization.

Method: POST
Endpoint: /v1/projects
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true,
“subProjects”: [
{
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true
}
],
“clientUuid”: “string”
}

As mentioned above there are a couple of differences from the Asset creation endpoints including the parameters parentUuid, productsUuids, and subProjects.

parentUuid – [OPTIONAL] represents the UUID of another Project for which this Project will be a sub-Project.
productsUuids – [OPTIONAL] a list of UUID’s corresponding to Assets you wish to link to the newly created Project. Note: the Assets must be in a published state to be linked via the API.
subProjects – [OPTIONAL] a list of Project objects to be created as sub-Projects to the newly created Project.

Upon successful creation of a Project, you will receive a response like the following:

{
“success”: true,
“errors”: [],
“response”: {
“uuid”: “string”,
“clientUuid”: “string”,
“name”: “Postman Test”,
“description”: “”,
“thumbnailUuid”: “”,
“status”: “LIVE_INTERNAL”,
“locations”: [],
“tags”: [],
“attributes”: {},
“productsUuids”: [],
“parentUuid”: “”,
“subProjects”: null,
“created”: “2023-11-09T02:51:26.003384”,
“updated”: “2023-11-09T02:51:26.003384”
}
}

Project Updating

Updating a Project via the API simply requires calling the same endpoint as creation using a PUT request and including the Projects UUID in the request body.

Method: Put
Endpoint: /v1/projects
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“uuid” : “string”,
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true,
“subProjects”: [
{
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true
}
],
“clientUuid”: “string”
}

There is no difference between the data that gets returned from an Update call versus a Create call. Like with updating an Asset, any information contained in the Project that you wish to retain (tags, attributes) have to be passed within the body of the update request. In addition to this, because the key purpose of Projects is to link Assets, it is imperative that you remember to include all Assets and Sub-Projects information within the the request body as well in the productsUuids and subProjects parameters.

Publish Status Only Projects which are in a Live Internal or Live Public state can be updated via the API.

Unique Errors

PROJECT_IS_NOT_PUBLISHED

This error is returned when attempting to Update a Project which is in DRAFT status. Only Live Projects can be updated via the API.

Postman Collections

You can test the above endpoints with the following Postman collection. This collection contains both the Create and Update endpoints, as well as all the endpoints required to Authenticate. 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