Threekit's REST APIs

While Threekit's Introduction: Client Side APIs are powerful ways to facilitate configuration & interactivity in a 3D space, the REST APIs will allow you to interact directly with the Threekit platform to create tools/utilities, robust integrations, and more.

Getting Started

Authentication

All of the GET API endpoints can be used both on the client-side as well as on server side applications. When using them on the client-side, care must be taken to use only public tokens.
All other API endpoints can only be accessed from the server-side.

When using the API endpoints with a Bearer authentication token, there is no need to provide the orgId as well. This is because tokens created in an org will be specific to that org only, and the platform will understand that when an API request is made with a Bearer token.

We realize that many API endpoints currently list the orgId as required, but it is not actually the case. We will try to update these pages in the future to clarify that.

Cookie Token

The only time the orgId is required is when a Cookie token is used for authentication. The Cookie token is provided only when embedding the web app into the org using the procedure outlined here.

Embedded apps will receive the following info through the URL query params: appid, token, orgId, hostname and branch.

App Deployment

ThreeKit offers app deployment for both front-end apps as well as for back-end maintenance apps. Contact support@threekit.com if a GitHub link to the repo hasn't been provided already for your project.

When deploying the app with ThreeKit, we require the apps to be developed using Next.js with TypeScript. This ensures that our team can more easily provide support when needed. Additional details for database access and server resources can be provided as well if needed.

Available APIs

The following is a brief explanation of the purpose for each server-side API.

Analytics

The purpose of the analytics service is to capture session information of a user interacting with Threekit configurators/viewers. Customers can access raw analytics data from Threekit for use in their Business Intelligence solutions.

Assets & Catalog - Simple

Simple management of assets and items, with less detailed information being passed back and forth.

Assets & Catalog - Granular

This set of APIs allow for granular editing of individual assets and items in the platform.

Assets & Catalog - Bulk

Used for importing and updating items, along with all their metadata, into the platform using JSON format. Can be used for updating multiple items that match the criteria defined in the query object. Also used to update configuration attributes and rules.

Assets & Catalog - Legacy

This is a legacy set of APIs, largely replaced by the APIs listed above.

Used for retrieving a list containing all item data from all items matching your specified query accessible by the authentication token used. Can be useful for mapping item names to item Ids when using the Configurator API.

Assets & Catalog - Import and Export Jobs

Used for importing and exporting assets to/from the platform. For importing, used in conjunction with the Files API.

Branches

Manage branching inside a given org.

Data Tables

Manage Data Tables inside an Org, including import and download functionality. Data Tables can be used for a variety of tasks, to help automate portions of a project's architecture.

Fast Compositor

The Fast Compositor service allows for quick generation and serving of composite images from previously generated renders located in the layer service. These composites are a single image per configuration, useful for PLPs (Product Listing Pages), carousels, or order documents, where embedding the 2D Player would not be possible or performant.

File Service

Used for uploading and retrieving files to/from the Threekit Platform CDN. Main usage from an implementation standpoint is for uploading assets into an organization in conjunction with the Asset API.

Jobs Service

These API endpoints allow for management of the underlying Jobs system. The user can create, retrieve, or updated individual Jobs.

Jobs Tasks

Manage individual tasks inside a job.

Jobs Runs

Manage Job Runs in terms of creating, retrieving, or updating individual runs.

Layers Service (Renders & AR)

The layers service is a way to keep track of renders and exports of specific assets and their configurations. For example if there is an asset with 10 different configurations, it is not ideal to generate a render for all 10 configurations every single time a render job is triggered. Generate it once, make sure it is stored in layer-service, and just call the layer service to fetch that particular file.

Orders

This API is designed to be used by connectors, for example, Shopify integration. If an order is placed in an app like Shopify, those order details should also be stored in our database.

Orgs

Retrieves an organization from its ID. Only works for the token's organization, and any public organization.

PDF Service

This service will allow you to create PDFs from a Liquid File with JSON inputs. You can find an example of inputs here.

Pricebooks

Allows for control over the pricebook system inside an org.

Saved Configurations

Used for saving and accessing saved configurations. It is used by the sharing function to resume the configurator state.

Tags

Tag Management system which enables the user to create, retrieve, or edit tags within a given org.

Webhooks

Webhooks can be used to trigger a number of things in the platform on the basis of some event.