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.
The Admin API now allows for the cloning and moving of your 3D assets within your Organization without the need to download and re-upload to the new destination. You can indicate the Folder you wish the Product to be located in, indicate the Publish status for it to have, as well as indicate new Optimization settings when cloning.
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.
-
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.
-
Cloning a Product
The clone method allows you to take a Product and clone or copy it’s data and 3D asset to a new Product without losing the original. The cloned Product can be placed in the same Folder or in a different Folder. While the manual clone method on the Platform does not allow you to create a new Folder as part of the clone process, this can be accomplished via the API as this is a separate method and just needs to be handled before making the request to clone. See the section below on ‘Creating a Folder’ to see how to handle this.
The endpoint for cloning a Product is as follows:
Most of the parameters resemble the data that can be passed when creating a Product as this is similar in nature. There are some additional parameters to consider however.
- clientOrganization: Indicates the organization, with name and slug being retrieved by the Get Organizations endpoint used in the Authentication flow.
- cloneHotspots: Indicates whether to copy over the same Hotspots that have been created on the original.
- cloneAnnotations: Indicates whether to copy over the Annotations that have been created on the original.
- cloneAttachments: Indicates whether to copy over the Attachments that have been uploaded to the original.
- modelOpsParameters/pipelineUuid: You do not need to pass either of these in the request body, and omitting them will ensure the cloned Product retains the same settings as the original. If you wish to change any of these settings, you can pass them here.
- tags/attributes: If you wish for these to be passed along with the cloned Product, you will need to include them in this request. They can be pulled from a retrieving a products information using this guide.
Moving a Product
The manual process of moving a Product on the Platform allows you to create a new Folder at the same time and immediately move the Product into this folder. In order to do this via the API you must separately create the Folder as detailed below in the section ‘Creating a Folder’.
When moving a Product, you can call the following endpoint:- sourceProductUuid: The productUuid of the Product you wish to move.
- targetClientUuid: The clientUuid of the Folder you wish to move the Product to.
- targetClientOrganization:
- organizationUuid: [Required] The UUID of the organization.
- name: [Optional/Required] The name of the organization you wish to move within/to. This is optional if you are passing a refreshToken in the headers, however if you are doing an unauthenticated move you need to include this and the slug.
- slug: [Optional/Required] Unique identifier based on name. This is optinal if you are passing a refreshToken in the headers, however if you are doing an unauthenticated move you need to include this and the name.
- imageBlobId: [Optional] The BlobId of the Organization’s thumbnail.
- publishToStatus: The status you wish the moved Product to be in after moving.
Creating a Folder
In order to clone or move a Product into a new Folder, the Folder must first be created. This can be accomplished using the following endpoint:
- imageBlobId: [Optional] the BlobId of a thumbnail you’ve uploaded to identify the Folder.
- name: [Required] The name of the Folder.
- slug: [Required] The slug of the Folder. This is a unique identifier of the Folder since you can have multiple Folders of the same name. This will usually be very similar to the name. You can utilize the endpoint /v1/clients/slug-availability to check if your slug is available for use. If it isn’t, it will return a recommended slug to use.
- organizationUuid: The UUID of the Organization the Folder belongs to.
Postman Collections
You can test the above endpoints with the following Postman collection. This collection contains everything you need to clone or move products, from authentication to creation. 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.