API – Linking Assets to Projects

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.

A key component of Projects is the ability to link Assets to a Project or sub-Project. While you can easily handle this when creating your Assets or Projects, it is also possible to handle it after the fact.

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.

Linking Assets to Projects does not in any way change the Asset. Though you can make certain synchronized changes such as having a Project status change trickle down to all linked Assets, generally linking is just a symbolic action allowing you to categorize or otherwise organize your Assets in ways that work best for your needs.

To link an Asset to a Project via the API, you will need to make a call to the following endpoint:

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

You will notice three key parameters: uuids, productsUuids, and project. These allow you to link multiple Assets to multiple Projects.

uuids: a list of Project UUID’s to link the Assets to.
productsUuids: a list of Asset UUID’s to link to the above Projects.
project: a project to be created (what is this doing? did I test this?)

Important: only Projects and Assets that are in the Live Internal or Live Public state will be handled by this endpoint. Any that are in Draft will be ignored, and in the event all productUuid’s or uuids are in Draft, the endpoint will return an error.

Upon successful linking, you will receive a count indicating the number of links made. The reason for this is due to the possibility that of the uuids and productsUuids passed, some may not be able to form links if they are in DRAFT state. See below for a successful response as well as notable errors.

{
“success”: true,
“errors”: [],
“response”: {
“count”: 1
}
}

Errors

PROJECT_IS_NOT_PUBLISHED

This error message indicates none of the uuids that were passed are published. If at least one Project is published, this error will not be returned.

PRODUCT_IS_NOT_PUBLISHED

This error message indicates none of the productsUuids that were passed are published. If at least one Asset is published, this error will not be returned.

Note: in both of the above cases, there is one exception: if none of the passed Projects and Assets can be found to be in the same Workspaces, those errors could be returned depending on the dominant parameter with respect to their UUIDs.

Postman Collections

You can test the above endpoints with the following Postman collection. This collection contains everything you need for Authentication as well as the Linking endpoint. 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