Resources

Rest API Documentation V1.2

Rest API Quick Start Guide

This guide will give you a brief overview of how to use the VNTANA Admin API in order to login to our Platform, authenticate your account, and retrieve your organizations, clients, products, and any additional information about your products, such as tags and locations. For a more comprehensive overview of our API, please check out our detailed API Documentation here. We also have a public API that you can use to access your published products and hotspots. Documentation for the public API can be found here.

Base URL: https://api-platform.vntana.com

To test most of the endpoints discussed in this guide, you can download this set of Postman collections: VNTANA API Postman Collections

  • For each collection, you can either set the email and password for login with the Pre-Request Script of each collection, as well as the desired organizationSlug and ClientSlug you wish to work with. You can further adjust these collections as you see fit to test more features.

Login to the VNTANA Platform

  • Use the following endpoint to authenticate

Method: POST
Endpoint: /v1/auth/login
Sample Request Body: { “email”: “youremail@address.com”, “password”: “YourPassword1” }

  • On successful authentication, a temporary user authentication token, X-AUTH-TOKEN, will be returned in the Response Headers.
  • This X-AUTH-TOKEN will only be used to authenticate with a specific Organization on the Platform.

Retrieve your Organizations List

  • After authentication, you can retrieve the list of your Organizations using the X-AUTH-TOKEN Response Header from Step 1, passed as a header in the GET Request below:

Method: GET
Endpoint: /v1/organizations
Headers: { “x-auth-token”: “Bearer ” + token }

  • The token is the X-AUTH-TOKEN value retrieved from the Login Response Headers. Don’t forget to add “Bearer ” before your token value.
  • The response has the list of all the Organizations in your Platform account, including important details such as the name, role, slug, and uuid of each Organization.
  • An example of a Response Body is:

{
  “response” : {
    “grid” : [
      { 
        “created” : “timeStamp”,
        “imageBlobId” : “string”,
        “name” : “Some Organization”,
        “role” : “SUPER_ADMIN”,
        “slug” : “some-organization”,
        “uuid” : “string”
      }
    ],
    “totalCount” : 0
  },
  “success” : true
}

  • uuid: Unique identifier for an Organization that will be used to authenticate with said Organization.
  • name: Non-unique – simply the name of the Organization.
  • slug: Either generated or set by the Organization creator at set-up, acts to identify the workspace so similarly named Organizations can be found.
  • role: indicates the role the logged in user has with the Organization.
  • created: Timestamp indicating when the Organization was created.
  • imageBlobId: An ID for a “profile image” uploaded for the Organization.

Authenticating a Specific Organization (Retrieve the Refresh Token)

  • In order to authenticate a specific Organization to see the Clients and Products for that Organization, you must retrieve the Refresh Token, which is an Organization-specific token.
  • Pass the X-AUTH-TOKEN, as well as the UUID of the Organization you would like to view, as headers in the following endpoint:

Method: POST
Endpoint: /v1/auth/refresh-token
Headers: { “x-auth-token”: “Bearer ” + token, “organizationUuid”: uuid }

  • The token is still the same X-AUTH-TOKEN retrieved from the successful Login Response Headers (don’t forget to add “Bearer “ to the beginning of the X-AUTH-TOKEN), and the Organization UUID can be found from the list of Organizations returned in Step 2.

  • On successful authentication of the selected Organization, you will receive another X-AUTH-TOKEN Response Header. This is the Refresh Token for this Organization. Please keep in mind that the X-AUTH-TOKEN from Step 1 is different from the one described in this step (Step 3), and in order to interact with anything within the desired Organization you must have a valid Refresh Token for it.
  • You can now access your Clients / Folders and Products for this Organization!

Retrieve Clients List for Selected Organization

  • Pass the Refresh Token retrieved from the previous step (Step 3) to the following endpoint in order to get your list of Clients for the selected Organization:

Method: GET
Endpoint: /v1/clients/client-organizations
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • A successful response will return the list of Clients for the selected Organization, as well as the name, role, slug, uuid, and other details for each Client.
  • Much like the Response Body for the Organizations retrieval, a sample body is as follows:

{
  “response” : {
    “grid” : [
      { 
        “created” : “timeStamp”,
        “imageBlobId” : “string”,
        “name” : “Some Client”,
        “role” : “SUPER_ADMIN”,
        “slug” : “some-client”,
        “uuid” : “string”
      }
    ],
    “totalCount” : 0
  },
  “success” : true
}

  • uuid: Unique Identifier for a Client / Folder that will be used extensively with further API commands.
  • name: Non-Unique name for the Client / Folder.
  • slug: Either generated or set by the Client / Folder creator at setup, acts to identify the Client / Folder so similarly named Clients / Folders can be found.
  • role: Indicates the role the logged in user has with the Organization (same as above).
  • created: Timestamp indicating when the Client / Folder was created.
  • imageBlobId: An ID for a “profile image” uploaded for the Client / Folder.

Authenticating a Specific Client (Retrieve the Refresh Token)

  • For users with Folder level access, in order to interact with a Client / Folder via the API a Refresh Token must be retrieved for the selected Client / Folder.
  • Pass the X-AUTH-TOKEN, as well as the UUID of the Client you would like to view, as headers in the following endpoint:

Method: POST
Endpoint: /v1/auth/refresh-token
Headers: { “x-auth-token”: “Bearer ” + refreshToken, “organizationUuid”: organizationUuid, “clientUuid”: clientUuid }

  • The refreshToken here is the same refreshToken retrieved from authenticating the Organization in Step 3 and passed in the headers in Step 4. The Client UUID can be found from the list of Clients returned in the previous step (Step 4).
  • On successful authentication to the selected Client, you will receive another X-AUTH-TOKEN Response Header. This is the Refresh Token for this Client. Please keep in mind that this Refresh Token is different from the Organization Refresh Token from Step 3.
  • You can now access your Products and Client related items (e.g. Locations, Tags) for this Client.
  • Note: If you have Organization level access, you don’t authenticate with specific Clients / Folders so this step should be skipped.

Retrieve Products for Selected Client

  • In order to view the Products for a single Client, use the following endpoint:

Method: POST
Endpoint: /v1/products/clients/{clientUuid}/search
Sample Request Body: { “page”: 1, “searchTerm”: “string”, “size”: 10, “status”: “LIVE” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The “x-auth-token” header here also requires the Client-specific Refresh Token returned in the Response Headers of the previous step (Step 5) if you have Folder level access, or Step 3 if you have Organization level access (Organization level users do not authenticate with a specific Client / Folder).
  • The list of Products retrieved can be filtered in a number of ways, including by Search Term, Tags, Locations, and Conversion Statuses. The full options for the Request body are as below:

{
  “attributeKey” : “someKey”,
  “attributeValue” : “someValue”,
  “clientUuids” : [ “clientUuid” ],
  “conversionStatuses” : [ “PENDING” ],
  “description” : “string”,
  “locationName” : “string”,
  “locationsUuids” : [],
  “name” : “Some Product Name”,
  “organizationUuid” :  “someUuid”,
  “page” : 1,
  “size” : 10,
  “searchTerm” : “someSearchTerm”,
  “sorts” : {},
  “status” : [  “LIVE”, “DRAFT” ],
  “tagName” : “someTag”,
  “tagsUuids” [  “someTagUuid”, “someOtherTagUuid”  ],
  “variantGroupName” : “someVariantGroup”,
  “variantGroupUuids” : [  “someVariantUuid” ]
}

  • Not all of these parameters need to be included in the Request, only ‘page’ and ‘size’ as these indicate the number of results to return and from which page (i.e. page 1 size 10 means the first page of 10 results will be returned).
  • This endpoint can be tested using the Search Product in Client-Folder collection from the API Collections linked at the top of the page.

Retrieve Locations

  • Locations can be created for the Products on the Platform and are linked to the specific Client / Folder they are created in.
  • Use the following endpoint to get the list of Locations created under a specific Client / Folder:

Method: POST
Endpoint: /v1/locations/search
Sample Request Body: { “clientUuid”: clientUuid, “page”: 1, “size”: 5, “searchTerm”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • clientUuid: This is the Client / Folder UUID retrieved from the list of Clients returned in the Response Body of the Get Clients endpoint – Required.
  • page: Indicates the page of results you wish to have returned with 0 being the first page – Required.
  • size: Indicates the number of results you wish to be returned per page – i.e. page 0, size 10 will return the first 10 results found – Required.
  • searchTerm: A string that aids the search by filtering results based on relevancy, returning exact or near exact matches first. – Not required, but do note that without it the call will simply return however many results you indicate with ‘size’ with no filtering.
  • The Client-specific Refresh Token must also be passed as an “x-auth-token” header.
  • You can test out this endpoint with the Retrieve Locations collection from the Postman collections linked above.

Retrieve Tags

  • Use the following endpoint to get the list of Tags created under a specific Client:

Method: POST
Endpoint: /v1/tags/search
Sample Request Body: { “clientUuid”: clientUuid, “page”: 1, “size”: 12, “searchTerm”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The UUID for the selected Client must be passed in the request body.

  • Tags can be filtered by page, size, and search term.

  • The Client-specific Refresh Token from must also be passed as an “x-auth-token” header.

  • You can test out this endpoint with the Retrieve Tags collection from the Postman collections linked above.

Additional Notes

  • These first five steps are the foundation of interacting with the VNTANA API, you will always need to retrieve the Refresh Token for the specific Organization – Client / Folder combination that you wish to work with.

  • If you already know the Organization UUID and Client / Folder UUID that you wish to work with, you need only call the Login and Refresh Token endpoints to authenticate with these before being able to work with the rest of the API, just plug in the known UUIDs where necessary.

  • In order to authenticate another Organization, the Refresh Token for that Organization must be retrieved (repeat Step 3). Simply pass the temporary user authentication token from Step 1, as well as the UUID of the Organization you wish to view (retrieved from Step 2), into the Refresh Token endpoint (Step 3). On success, you will be able to see the Refresh Token (Organization-specific token) for the Organization you have selected to view.

  • Once you have the new Refresh Token, you can repeat Steps 4-8 in order to retrieve the Clients in that Organization, authenticate into the desired Client, and then retrieve the Products, Locations, and Tags for that Client. 

One of the important concepts as part of the VNTANA Platform are Products. Products are essentially an overarching entity for 3D assets that hold not only the raw (original) 3D asset, but also the converted and optimized versions in GLB and USDZ formats, as well as the metadata that goes along with any 3D models.

Products

Create a Product

  • Use the following endpoint to create a Product:

Method: POST
Endpoint: /v1/products
Sample Request Body: {
“clientUuid”: “[CLIENT UUID]”,
“name”:”Sample Product Name”,
“pipelineUuid”:”[PIPELINE UUID]”,
“autoPublish”:false,
“modelOpsParameters”:{
“OPTIMIZATION”:{
“desiredOutput”:”AUTO”,
“obstructedGeometry”:”false”,
“poly”: “0”
},
“DRACO_COMPRESSION”:{
“enabled”:”false”
},
“TEXTURE_COMPRESSION”:{
“aggression”:”4″,
“maxDimension”:”2048″,
“lossless”:”false”
},
“AR_SCALING”:{
“dimension”: “x”,
“size”: “1.5”
}
},
“attributes”:{
“attribute key”:”attribute value”
}
Headers: { “x-auth-token”: “Bearer ” + [X-Auth Refresh Token] }

  • clientUuid is the Client UUID. This is a required parameter.

  • name is the name of the product. This is a required parameter.

  • pipelineUuid is the UUID of the pipeline you would like to process your model with. You can retrieve the pipeline UUID with the /v1/products endpoint. Please refer to the API documentation for details.

  • autoPublish is the boolean flag that determines if the product should be auto-published once the processing is COMPLETE. It is important to note that you can only auto-publish if you have Client Admin or Organization Admin privileges.

  • modelOpsParameters is a nested object that defines 3D and texture optimization and compression parameters.
    • OPTIMIZATION defines the 3D model decimation levels (reduction of polygon and vertex count). If you set it as null, no optimization will happen.
      • desiredOutput: If set to AUTO, the optimization smart algorithm will automatically detect the level of decimation to achieve the smallest file possible at the best quality possible. If set to CUSTOM, the optimization process will look for the poly count defined by the poly parameter.
      • poly: An integer value that defines the maximum polygon count you desire to achieve.
      • obstructedGeometry: (beta) A boolean flag that defines whether you would like to remove parts and polygons of the model that are not visible to the outside world. This helps to reduce the model poly count further. Keep in mind this feature is currently in beta testing and may not give you the best results. We recommend using this only if you would like to experiment with it.
    • DRACO_COMPRESSION enables Draco Compression on the model. Draco compression only applies to the final GLB files. It helps reduce the file size up to 5 times.
    • TEXTURE_COMPRESSION enables Texture Compression if it is defined. If you pass null as the value, the texture compression will be disregarded.
      • lossless: A boolean flag that determines the method of compression. The VNTANA Platform currently supports Lossless and Lossy comparisons. Setting lossless to false will automatically use lossy compression.
      • aggression: Determines the compression aggression, but only for lossy compression. If you choose lossless as the compression type, the aggression parameter will not make any difference. Our recommended aggression level is 4.
      • maxDimension: Defines the maximum power of two size of a texture. This parameter accepts 512, 1024, 2048, 4096, and -1 as values. If set to -1, texture compression will preserve the original texture sizes.
    • AR_SCALING is an optional utility designed for Web AR. This option allows you to resize the model, so it shows in the correct size in the Web AR experience.
      • dimension: Defines the axis at which you desire to proportionally scale the model.
      • size: The size in meters.
  • attributes allow you to define extra metadata that you can associate with your product. For example, you can define an alternative SKU or vendor product ID as an attribute you would be able to search by. It accepts key value pairs. There is no limit to how many attributes you can define per product.
  • On successful creation of a Product, the uuid of the Product will be returned in the response body. You will need the uuid for uploading the actual 3D asset that will be processed based on the parameters you have defined for your product. You will also need the UUID to search, edit, or delete the product.

Searching Products

To expand on the segment on retrieving Products for a selected Client / Folder, there are a number of methods one can use to filter the results of Product retrieval, including searching by Attributes, Tags, Configurations, and more.

Search Products by Attribute

  • One method of filtering is via a single Attribute applied to a Product. In the Request Body, you can pass the Attribute key and value, however you cannot include spaces.
  • In the event that you have a two or more word attribute key or value, you can simply pass one of the words, and it’ll still show up in the search, i.e. passing “Fabric Type” as just “Fabric” (though it would be best to include another Request parameter in this case to help narrow it down in the event that the attribute loses some level of uniqueness by only passing one word). This is because it utilizes a fuzzy search which returns results based on relevance, more on this below.
  • You can test this method using the Search Product by Attribute collection from the collections linked above.
    • Note: you will have to already have a product that contains an attribute to search for.
    • Simply replace the values for the attributeKey and attributeValue within either the body directly or the Pre-Request Script of the Search Products endpoint.

Search Products by Tags

There are two different methods to utilize Tags to search for products, Tag Names and / or Tag UUID’s.

  • If you wish to see products in a Client / Folder that have a specific Tag or Tags, you can pass the name(s) of the tags in the Request Body under “tagName”. Though passed as a single string, multiple tags can be passed, and unlike with Attributes spaces are acceptable.
  • An example of this, if you have two separate Products, one with tag ‘Double Knit’ and another with ‘Woven’, you can add the tagName parameter as “Double Knit Woven” and it will return both products in the results. It will, however, also include any product with a tag consisting of only ‘Double’ or ‘Knit’.
  • You can test this with the Search Product by Tag Name collection from the Postman collections linked above, simply add the tagName you wish to search for in the Body of the Search Products endpoint.
  • Alternatively, you can pass a list of tag UUID’s, returning any products that have these tags, with those containing more than one match shown first. This list is passed in the Request Body as the parameter “tagsUuids”.
  • You can test this with the Search Product by Tag UUIDs collection from the Postman collections linked above.
    • You can set the global “exactTag” for the collection to the Tag UUID you wish to search for.

Additional Notes on Searching

  • All searches utilizes a “fuzzy” search principle, meaning the results are returned based on relevance to the given search parameters. Therefore, complete search terms aren’t absolutely necessary, they just help to narrow the search in on what exactly you may be looking for.
  • The “page” parameter is necessary for every search endpoint, however it’s starting value differs depending on the search you are conducting. Page 1 indicates the first page of results for searches that return the following: Products, Variant Groups / Configurations, Tags, and Locations. In contrast to these, Page 0 indicates the first page of results for searches that return the following: Comments, Annotations, Attachments, Showrooms, and Hotspots. You can see more details about each of these endpoints in the full API documentation linked above.

Edit or Delete a Product

Updating a Product

After you have created a Product, you can always edit it. The request body is almost the same as described in the product creation above with a few additional required parameters.

Method: PUT
Endpoint: /v1/products
Sample Request Body: {
// ALL PARAMETERS DESCRIBED IN THE PRODUCT CREATION ABOVE
“uuid”: “[PRODUCT UUID]”,
“deleteAsset”: “false”
}
Headers: { “x-auth-token”: “Bearer ” + token }

  • uuid is the uuid of the product that has been returned after the product has been created.

  • deleteAsset is a boolean flag that determines whether the asset associated with the product should be deleted. Note that if set to true you will have to re-upload an asset for a product.

  • You can test out editing a Product’s information and settings with the Update Product collection from the Postman collections linked above. 

Delete a Product

To delete a product, the desired products UUID must be passed to the below endpoint in the Request Body, along with the X-AUTH-TOKEN as a Request Header, this being the Refresh Token obtained for a specific Organization or Client / Folder.

Method: DELETE
Endpoint: /v1/products/delete
Sample Request Body: { “uuids”: [  “productUuid”  ] }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • This will delete the Product and Asset from the Platform. You can pass more than one Product’s UUID in the Request Body to delete more than one at a time.
  • You can test out deleting a Product using the Delete Product collection from the Postman collections linked above.

Upload an Asset for a Product

After you have created a Product, you will need to upload the raw 3D for it. The upload process has a few steps. To make sure the upload process is secure, we first require you to retrieve the signed URL through an endpoint. Once you have the signed URL, you will have 15 min to upload the asset. First things first, let’s get the signed URL.

Method: POST
Endpoint: /v1/storage/upload/clients/products/asset/sign-urls
Sample Request Body: {
// ALL PARAMETERS DESCRIBED IN THE PRODCT CREATION ABOVE
“clientUuid”: “[CLIENT UUID]”,
“productUuid”: “[PRODUCT UUID]”,
“resourceSettings”: {
“contentType”: “application/octet-stream”,
“originalName”: “SmpleFileName.glb”,
“originalSize”: [FILE SIZE IN BYTES]
}
}
Headers: {
“x-auth-token”: “Bearer ” + token,
“Origin”:: “The origin domain wher the upload will be coming from”
}

  • clientUuid is the Client UUID. This is a required parameter.
  • productUuid is the Product UUID. This is a required parameter.
  • resourceSettings is the object that defines the details about the origin size and the type of file.
    • contentType is the mime type for the file. For 3D assets, it will usually be application/octet-stream.
    • originalName is the domain where the upload will be originated from.
    • originalSize is the size of the file in bytes.

Now that you have the signed URL, you can trigger the upload process.

Method: PUT
Endpoint: [SIGNED URL]
Sample Request Body:
[file data]

Headers: {
“Content-Length”: [FILE SIZE IN BYTES],
“Origin”:: “The origin domain wher the upload will be coming from”
}

  • The body requires that you stream the file’s data in the PUT request.
  • An example of this endpoint can be explored using the Upload Asset collection from the Postman collections linked above.
    • This collection requires the most amount of input from the user to use. You first need to set the Pre-Request Script of the collection itself (not each individual endpoint) to contain the parameters for authentication, organizationSlug, and clientSlug.
      • You can also change the name of the product in the Create Product endpoint, by default the collection sets it to “Testing”.
    • In the endpoint Get Signed URL, the name of the file you wish to upload has to be entered in the Request Body, as well as the file size in bytes.
    • In the endpoint Upload Asset, you need to add the file to the binary section of the Request Body, as well as add the file size in bytes once more, this time as a header.
      • Note: you may also need to change a setting in Postman, by default it doesn’t allow the sending of file data for file’s located outside of its’ designated workspace. To handle this, you can either place the file in the workspace Postman creates at install, or alternatively you can open it up to accept files located elsewhere by going to File > Settings > General Tab and toggle “Allow reading files outside working directory”.

Additional Notes on Product Calls

  • You can create Preset parameters on the Platform to use when uploading an asset, however this is currently not a publicly available feature in the API. Revealing this to the public API is planned.

Starting from version 1.2 of the VNTANA Admin API, you can now perform actions related to Annotations and Comments. Annotations allow you to leave pins directly on the 3D model with text notes for yourself or your team to see. With Comments, you can provide feedback or add notes for the entire Product from the Product Details Page. Below, you can find a few examples on how to use the API to create, edit, or delete Annotations and Comments.

Annotations

Create an Annotation

  • Though Annotations exist in 3D space, and as such have 3D coordinates determining their position, it is possible to create an annotation via the API using the following endpoint:

Method: POST
Endpoint: /v1/annotations
Sample Request Body: {
“attachments”: [ “blobId” : “string”, “name” : “string”, “productUuid” : “string” ],
“clientUuid”: “string”
“dimensions”: “{\“position\”: \“0.0017966393878431288m 0.01154611014484365m 0.002267831995077924m\”,\”normal\”: \“0.4475415981843541m 0.8250387565067864m 0.3449892290439372m\”}”,
“productUuid”: productUuid,
“text”: “The color of this fabric should be blue, not green.”
}
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • annotations: An attachment can be uploaded with the Annotation, allowing another user to download it. This can be an image representing how the model should look, or for example a json file containing information the other user may need.
    • blobId: The UUID of the attached file.
    • name: The name of the attached file.
    • productUuid: The UUID of the attachment itself (details including name, creation timestamp, and file ID, etc.). This is what would be used should you wish to search for the attachment via the API.
  • clientUuid: The UUID of the Client / Folder containing the Product you wish to create an annotation for.
  • dimensions: A stringified json object containing 3D position and normals as strings. It is very important that you escape the double quotes found within the parameter or the front-end won’t be able to parse the information correctly and will cause issues.
    • The sample above shows this exactly as it needs to be entered. With the exception of the first and last double quote (“), you must place a \ in front of each interior double quote.
  • productUuid: The UUID of the product for which the Annotation will be created.
  • text: The text content of the Annotation.
  • All are required, however for attachments you can simply pass an empty list ([ ]) if you have nothing to attach. It you do choose to pass an attachment you must first create it, you can view the full API documentation linked above to see how to upload an attachment through the API.
  • You can test this endpoint using the Create Annotation collection from the Postman collections linked above.

Edit an Annotation

  • After you have created an Annotation, you can always edit its position or text:

Method: POST
Endpoint: /v1/annotations
Sample Request Body: {
“attachments”: [ “blobId” : “string”, “name” : “string”, “productUuid” : “string” ],
“clientUuid”: “string”
“dimensions”: “{\“position\”: \“0.0017966393878431288m 0.01154611014484365m 0.002267831995077924m\”,\”normal\”: \“0.4475415981843541m 0.8250387565067864m 0.3449892290439372m\”}”,
“productUuid”: productUuid,
“text”: “The color of this fabric should be blue, not green.”
“uuid” : annotationUuid
}
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • As you can see, the Request Body is almost identical to the Request Body of the Create Annotation endpoint, the only difference being the inclusion of the parameter uuid.
  • uuid: The UUID of the Annotation you are editing.

Retrieve the Annotations for a Product

  • In order to see all of the Annotations for a product, you can use this endpoint:

Method: POST
Endpoint: /v1/annotations/search
Sample Request Body: { “page”: 0, “productUuid”: productUuid, “size”: 1000 }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • productUuid: Refers to the UUID of the specific product you wish to view the annotations of.
  • page: Indicates the page of results you wish to receive, with 0 indicating the first page.
  • size: Indicates the number of results that should be allocated to each page of results. You can set this high enough to retrieve all annotations in one result if you have a rough idea of how many there will be.
  • You can test out this endpoint using the Retrieve Annotations collection from the Postman collections linked above.
    • Note: This collection is set by default to only return the first annotation it finds, but this can easily be adjusted.

Reply to an Annotation

  • You can also reply to any existing Annotations via the API:

Method: POST
Endpoint: /v1/comments/create
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • You will pass Request parameters as path params, with the required params being entityType, entityUuid, and message.
  • entityType: This is the type of entity you are replying to, in this case ANNOTATION.
  • entityUuid: The UUID of the annotation you are replying to.
  • message: The body text of the reply you are making.
  • There are other params you can pass, see the full documentation linked above to view these.
  • Note: this endpoint can also be used to reply to normal comments, the entityType and entityUuid just need to reflect the comment correctly.
  • You can test this endpoint using the Reply to Annotation collection from the Postman collections linked above.

Comments

Create a Comment

  • In addition to adding comment responses to Annotations, you can also add Comments to your Products, which appear at the bottom of the Product Details Page:

Method: POST
Endpoint: /v1/comments/create
Sample Request Body : { “entityType” : “PRODUCT”, “entityUuid” : productUuid, “message” : “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • Notice here that the entityType is “PRODUCT” instead of “ANNOTATION.” These Comments will be appended to the overall Product Page.
  • After successfully creating a Comment, the response body will return the uuid of the Comment, which is needed to edit or delete the Comment.

Edit a Comment

  • Comments can also be edited after they are posted:

Method: PUT
Endpoint: /v1/comments
Sample Request Body: { “entityUuid”: “string”, “message”: “string”, “uuid”: commentUuid }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The entityUuid is the ID of the Entity you are updating. For example, if you are editing a Product Comment, then the entityUuid is the productUuid. If you are editing the response to an Annotation, then the entityUuid is the annotationUuid.
  • The uuid is the ID of the Comment itself.

Retrieve the Comments for a Product

  • All of the Comments for a Product can be retrieved with the following endpoint:

Method: POST
Endpoint: /v1/comments/search
Sample Request Body: { “entityType”: “PRODUCT”, “entityUuid”: productUuid, “page”: 1, “size”: 10 }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

  • The list of Comments retrieved can be filtered by Entity Type, Entity Uuid, Page, and Size. In this example, we only want the Product Comments, so the entityType is set to “PRODUCT”. If we wanted the list of replies to an Annotation, however, we could change the entityType to “ANNOTATION”. The entityUuid is again, either the uuid of the Product or the Annotation for which to retrieve Comments. Page and Size can also be changed to determine which subset of Comments to retrieve, and how many to retrieve per API call.

There is the concept of Configurators (colorways) in the world of apparel, shoes, and any goods. The VNTANA Platform provides tools to group 3D assets into meaningful configurators, which are tightly associated with products. You can select up to 100 products and add them to a configurator. You can also publish a configurator as a whole, the same way in which you can publish each product individually. You can do all this and more through the VNTANA API. Below is a quick start guide that can help you get started with configurators. Note: This feature was previously called ‘variant groups’ and as such the API endpoints reflect the old name.

Configurators

Create a Configurator

  • Use the following endpoint to create a Configurator:

Method: POST
Endpoint: /v1/variant-groups
Sample Request Body: {
“organizationUuid”: “{Org UUID},
“clientUuid”: “{Client UUID}”,
“description”: “Variant Description Text”,
“name”: “Variant Name”,
“productsUuids”: [
“{Product UUID}”
],
“tagsUuids”: [
“{Tag UUID}”
]
}
Headers: { “x-auth-token”: “Bearer ” + token }

  • organizationUuid is the Organization UUID. This is a required parameter.
  • clientUuid is the Client UUID. This is a required parameter.
  • name is the name of the Configurator. This is a required parameter.
  • productUuids is the array of UUIDs of products that you want to add to the Configurator. The product UUIDs can be found on the Product Details Page.
  • tagsUuids is the array of UUIDs of the tags you want to add to a Configurator.
  • organizationUuid, clientUuid, and name are the only required parameters.
  • You can test this endpoint using the Create a Variant Group collection from the Postman collections linked above.
    • Note: This collection still retains the old Variant Group naming as the endpoint itself still uses this.

Add Products to an Existing Configurator Group

  • After you have created a Configurator, you can add more products into it. You have the option to add the same product to multiple Configurators. The maximum number of products you can add to a Configurator is 100.

Method: PUT
Endpoint: /v1/variant-groups/add-products
Sample Request Body: {
“productsUuids”: [
“{Product UUID}”
],
“uuids”: [
“{Variant UUID}”
]
}
Headers: { “x-auth-token”: “Bearer ” + token }

  • productUuids is the array of UUIDs of products that you want to add to the Configurator. The product UUIDs can be found on the Product Details Page.

  • uuids is the array of UUIDs of Configurators that you want to add the products into. 

Retrieve a Configurator

  • To retrieve a Configurator, use:

Method: GET
Endpoint: /v1/variant-groups/{Variant Group UUID}
Headers: { “x-auth-token”: “Bearer ” + token }

Sample Response Body: {
“errors”: [
“MISSING_PAGE”
],
“response”: {
“clientUuid”: “string”,
“created”: “2021-11-19T00:22:04.584Z”,
“description”: “string”,
“name”: “string”,
“organizationUuid”: “string”,
“productsUuids”: [
“{Product UUID}”
],
“status”: “LIVE”,
“tags”: [
{
“name”: “string”,
“uuid”: “{Tag UUID}”
}
],
“updated”: “2021-11-19T00:22:04.584Z”,
“uuid”: “string”
},
“success”: true
}

  • You can test this endpoint using the Retrieve Variant Group collection from the Postman collections linked above.

    • Note: This collection still retains the old Variant Group naming as the endpoint itself still uses this.
  • If you do not know the Configurators UUID, you can use the following endpoint to search for it:

Method: POST
Endpoint: /v1/variant-groups/search
Headers: { “x-auth-token”: “Bearer ” + refreshToken }

Sample Request Body: {
  “page” : 1,
  “size” : 10,
  “searchTerm” : “string”
}

  • The request makes use of the Refresh Token to search the designated Organization or Client / Folder, and returns fuzzy results based on the searchTerm provided.

  • You can test this endpoint using the Search Variant Groups collection from the Postman collections linked above.

    • Note: This collection still retains the old Variant Group naming as the endpoint itself still uses this.

Additional Notes 

  • For any of the collections, you will need to set various global parameters in the collections Pre-Request Script as well as some of the individual endpoints Pre-Request Scripts. For the global parameters, these are the email and password for your login, an Organization slug, and a Client slug. These are for the Client / Folder you wish to test the API with.
    • Note: The slugs can be determined by navigating to the Platform and viewing the client you wish to test with. Both slugs will be found within the URL for that client page and will be similar if not the same as the name of the Organization or Client / Folder but with ‘-‘ in place of spaces. Just copy these exactly as they appear in the URL for use with the API endpoints.
  • For any endpoint that requires you to directly add a Product UUID, you can find this via the Search endpoint, or by simply navigating to the Product page on the Platform and copying it from the Product ID label.

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.