# Web API

We wrote an example Python script [here](<https://colab.research.google.com/drive/1QREQgxvLKDW30J87MhDufCPRdue6Dnsj?usp=sharing&#xA;>) that illustrates how to interface with our API.

We've also created a simple React app implementation on GitHub to help people with a quicker/easier implementation.

Link here: <https://github.com/Kaedim/API_Implementation>

## Credentials

To use the Kaedim API, you will need a devID, an API-key, and a refresh token. If you are part of a studio, you will also need to provide a studioID with some API requests.

You can find all three of these by logging in to the web app at [https://app.kaedim3d.com](https://app.kaedim3d.com/) and navigating to Settings > API Keys. There you should be able to see all the necessary info.&#x20;

If your keys are not working for any reason, don’t hesitate to contact us at <support@kaedim3d.com>.

{% hint style="info" %}
API Access is reserved for Enterprise customers.
{% endhint %}

<figure><img src="/files/dkQhKL1abVhYQXUDBFVd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Please note that clicking Copy on API Key, Kaedim Secret and Refresh Token, generates new values for these fields, making their previous values invalid!
{% endhint %}

## Step 1: Registering a webhook

To register a webhook endpoint you will need your API key and developer ID. Both of these can be found under your user settings page in the Kaedim app.

* Your API key should always be provided in the X-API-Key Header in your requests.

### Parameters

<table><thead><tr><th width="131">Name</th><th width="115">Requirement</th><th width="90">Section</th><th width="83">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-Key</td><td>Required</td><td>Head</td><td>String</td><td>User API key used to authenticate requests</td></tr><tr><td>devID</td><td>Required</td><td>Body</td><td>String</td><td>Your developer ID</td></tr><tr><td>destination</td><td>Required</td><td>Body</td><td>String</td><td>Your webhook endpoint url</td></tr></tbody></table>

{% hint style="info" %}
Please note that the following code is *Node.js*
{% endhint %}

```javascript
import fetch from "node-fetch"
const url = "https://api.kaedim3d.com/api/v1/registerHook"
const headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}
const body = {
    "devID": "your_dev_id",
    "destination": "your_endpoint_url"
}
try {
    fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}
```

201 Response

```json
{
    "status": "success",
    "message": "Webhook already registered"
    "jwt" : "eyJhbGciOiJIUzI1…"
}
```

404 Response

```json
{
    "status": "error",
    "message": "User does not exist"
}
```

Upon successful authentication you will receive a JWT, which needs to be added as a Bearer Token header on all processing requests. You will also receive a refreshToken to be used to generate a new JWT. Your JWT will expire after 12 hours. See below on how to refresh your token.

## Step 2: Processing an image

All processing requests must include the JWT in the Bearer Authorization header, alongside your API-key, and your devID inside the request body.&#x20;

### **Post processing request**

{% hint style="info" %}
<https://api.kaedim3d.com/api/v1/process>
{% endhint %}

### Parameters

<table><thead><tr><th width="126.33333333333331">Name</th><th width="161">Requirement</th><th width="152">Section</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-Key</td><td>Required</td><td>Head</td><td>String</td><td>User API key used to authenticate requests</td></tr><tr><td>Authorization</td><td>Required</td><td>Head</td><td>String</td><td>Your valid JWT<a href="https://docs.kaedim3d.com/devid"><br></a></td></tr><tr><td>devID</td><td>Required</td><td>Body</td><td>String</td><td>Your developer ID<a href="https://docs.kaedim3d.com/imageurls"><br></a></td></tr><tr><td>imageUrls/images</td><td>Required</td><td>Body</td><td>Array</td><td>An array with up to 6 image urls to be processed. Alternatively you can upload the files themselves in which case the parameter is called "images" and requires you to pass the files as blobs.<a href="https://docs.kaedim3d.com/loq"><br></a></td></tr><tr><td>LoQ</td><td>Required</td><td>Body</td><td>String</td><td>Level of quality: “standard”/”high”/”ultra”<a href="https://docs.kaedim3d.com/test"><br></a></td></tr><tr><td>test</td><td>optional</td><td>Body</td><td>Boolean</td><td>Used to process request as a test<a href="https://docs.kaedim3d.com/polycount"><br></a></td></tr><tr><td>polycount</td><td>optional</td><td>Body</td><td>Number</td><td>Upper polycount limit<a href="https://docs.kaedim3d.com/height"><br></a></td></tr><tr><td>height</td><td>optional</td><td>Body</td><td>Number</td><td>Desired height in cm (default 200)<a href="https://docs.kaedim3d.com/projectid"><br></a></td></tr><tr><td>width</td><td>optional</td><td>Body</td><td>Number</td><td>Desired width in cm</td></tr><tr><td>depth</td><td>optional</td><td>Body</td><td>Number</td><td>Desired depth in cm</td></tr><tr><td>projectID</td><td>optional</td><td>Body</td><td>String</td><td>The ID of the style you want this asset to have, if none it can be left null</td></tr><tr><td>studioID</td><td>optional</td><td>Body</td><td>String</td><td>Your team's studioID</td></tr></tbody></table>

{% hint style="info" %}
Please note that the following code is *Node.js*
{% endhint %}

```javascript
const url = "https://api.kaedim3d.com/api/v1/process"
const headers = {
  "Content-Type": "multipart/form-data",
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}

const data = {
  "devID": "your_dev_id",
  "LoQ": "standard",
  "imageUrls": ["https://example.com/image1.png","https://example.com/image2.png"],
  "polycount": 20000,
  "height": 250,
  "test": true // Turn this to false to pass a normal request
}

const json = JSON.stringify(data);

try {
  fetch(url, {
      method: "POST",
      headers,
      body:json,
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}
```

{% hint style="info" %}
Please note that the following responses are in JSON
{% endhint %}

201 Response

```json
{
"status": "success",
"devID": "ad39dg02-dief-as9i-ade0-g159g298ck6s",
"requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
"message" : "request sent successfully, please check webhook in 10-15 mins"
}
```

400 Response

```json
{
"status": "error",
"message" : "Request failed due to {reason}, please check your payload and headers and try again"
}
```

406 Response

```json
{
"status": "error",
"message" : "Invalid level of quality inputed"
}
```

{% hint style="info" %}
Please note that there is a 5MB limit per image file.
{% endhint %}

Once the asset has been successfully generated, a download URL will be sent to the registered webhook endpoint.

* Please note that you will need to perform a GET request on the URLs to get the file containing the completed asset

Each completed asset is available in 4 supported formats: obj, fbx, glb, and gltf all of which have separate download links in the post request.

* Download links expire after an hour
* We provide the functionality to fetch all requests

{% hint style="info" %}
We also provide the option for test requests using a boolean test body parameter. If set to true, a plain empty cube will be returned in the response. We recommend using this to get an idea of the structure of the response once an asset is completed.
{% endhint %}

Upon successful generation, you will receive a response similar to the following:

201 Response

```json
{
    "status": "success",
    "userID" : KaedimUser,
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "results" : {
        "obj": "https://....."
        "fbx": "https://....."
        "glb": "https://....."
        "gltf": "https://....."
    }
}
```

400 Response

```json
{
    "status": "error",
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "message" : "Asset creation failed"
    "cause" : "The request was too complex, we aim to deal with…"
}
```

Asset creation may fail due to various reasons some of which include: complexity, visibility of the object, multiple objects in the scene, inappropriate content, etc. Please see our guidelines for more information:  [Input Guidelines](/creating-assets/input-guidelines.md)

### **Other useful routes**

Check the progress and results of your generation

We provide functionality to check the progress of your generation based on the requestID

{% hint style="info" %}
<https://api.kaedim.com/api/v1/fetchRequest>
{% endhint %}

### Parameters

<table><thead><tr><th width="150.33333333333331">Name</th><th width="137">Requirement</th><th width="99">Section</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-Key</td><td>Required</td><td>Head</td><td>String</td><td>User API key used to authenticate requests</td></tr><tr><td>Authorization</td><td>Required</td><td>Head</td><td>String</td><td>Your valid JWT</td></tr><tr><td>devID</td><td>Required</td><td>GET Param</td><td>String</td><td>Your developer ID</td></tr><tr><td>requestID</td><td>Required</td><td>GET Param</td><td>String</td><td>The requestID of the asset you'd like to fetch</td></tr><tr><td>studioID</td><td>Optional</td><td>GET Param</td><td>String</td><td>Your team's studioID</td></tr></tbody></table>

{% hint style="info" %}
Please note that the following code is *Node.js*
{% endhint %}

```javascript
const url = `https://api.kaedim3d.com/api/v1/fetchRequest?devID=${devID}&requestID=${requestID}`

const headers = {
  "Content-Type": "application/json",
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}

try {
   fetch(url, {
      method: "GET",
      headers,
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}
```

{% hint style="info" %}
Please note that the following responses are in *JSON*
{% endhint %}

200 Response

```json
{
    "requestID": "81...236",
    "createdAt": "202...",
    "image": [
        "https://s...",
    ],
    "image_tags": [],
    "iterations": [
        {
            "createdAt": "2023-0...",
            "iterationID": "0",
            "results": {
                "obj": "https://s...",
                "fbx": "https://s...",
                "glb": "https://s...",
                "gltf": "https://s...",
                "mtl": "https://s...",
            },
            "status": "completed",
            "userID": "b6e...",
            "email": "mar...",
            "loq": "standard",
            "dismissedReason": null,
            "editDescription": null,
            "texturingMethod": null
        }
    , ...]
}
```

### Get All Assets

We provide functionality to retrieve all asset requests (even if they’re pending) based on date ranges (if provided).

{% hint style="info" %}
<https://api.kaedim3d.com/api/v1/fetchAll>
{% endhint %}

### Parameters

<table><thead><tr><th width="152">Name</th><th width="140">Requirements </th><th width="74">Section</th><th width="106">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-Key</td><td>Required</td><td>Head</td><td>String</td><td>User API key used to authenticate requests<a href="https://docs.kaedim3d.com/authorization"><br></a></td></tr><tr><td>Authorization</td><td>Required</td><td>Head</td><td>String</td><td>Your valid JWT<a href="https://docs.kaedim3d.com/devid"><br></a></td></tr><tr><td>devID</td><td>Required</td><td>GET Param</td><td>String</td><td>Your developer ID<a href="https://docs.kaedim3d.com/start-end"><br></a></td></tr><tr><td>start,end</td><td>Optional</td><td>GET Param</td><td>String</td><td>Date range provided in MM-DD-YYYY. If left blank all assets associated to the devID will be returned</td></tr><tr><td>studioID</td><td>Optional</td><td>GET Param</td><td>String</td><td>Your team's studioID</td></tr></tbody></table>

{% hint style="info" %}
Please note that the following code is *Node.js*
{% endhint %}

<pre class="language-javascript"><code class="lang-javascript">const devID = "your-devID";
const start = "2022-02-01"; // yyyy-mm-dd
const end = "2022-02-14";
const url = `https://api.kaedim3d.com/api/v1/fetchAll?devID=${devID}&#x26;start=${start}&#x26;end=${end}`
const headers = {
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}
<strong>try {
</strong>   fetch(url, {
      method: "GET",
      headers,
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}
</code></pre>

{% hint style="info" %}
Please note that the following responses are in *JSON*
{% endhint %}

200 Response

```json
{
    "assets": [
        {
            "requestID": "81...236",
            "createdAt": "202...",
            "image": [
                "https://s...",
            ],
            "image_tags": [],
            "polycount": "20000",
            "iterations": [
                {
                    "createdAt": "2023-0...",
                    "iterationID": "0",
                    "results": {
                        "obj": "https://s...",
                        "fbx": "https://s...",
                        "glb": "https://s...",
                        "gltf": "https://s...",
                        "mtl": "https://s...",
                    },
                    "status": "completed",
                    "userID": "b6e...",
                    "email": "mar...",
                    "loq": "standard",
                    "dismissedReason": null,
                    "editDescription": null,
                    "texturingMethod": null
                }
            ]
        },...
    ]
}
```

400 Response

```json
{
    "status": "error",
    "message" : "DevID is required, please make sure you are sending as a query parameter"
}
```

### Get All Projects

We provide functionality to retrieve all asset projects names and IDs

{% hint style="info" %}
<https://api.kaedim3d.com/api/v1/fetchProjects>
{% endhint %}

{% hint style="info" %}
Please note that the following code is *Node.js*
{% endhint %}

```javascript
const devID = "your-devID";
const url = `https://api.kaedim3d.com/api/v1/fetchProjects?devID=${devID}`
const headers = {
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}
try {
   fetch(url, {
      method: "GET",
      headers,
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}
```

{% hint style="info" %}
Please note that the following responses are in *JSON*
{% endhint %}

200 Response

```json
{
		"status":"success",
    "message": [
        {
            "projectID": "81...236",
            "name": "Sandbox",
            "studioID": "ad29cegh-adks-344j-htk4-aajs-6117d0jeddn5"
        },...
    ]
}
```

### Refreshing a JWT

Your web token will expire after 12 hours from its creation. You can only have one JWT valid at a time, therefore creating a new JWT will automatically invalidate the old token. To get a new JWT you must use the refresh token generated at webhook registration. You can find the refresh token in user settings in the Kaedim platform below the API-key.

### Post a refresh request in node.js

If successful, you will receive a new JWT that will allow you to make API requests that require authentication (such as /process etc.)

{% hint style="info" %}
<https://api.kaedim3d.com/api/v1/refreshJWT>
{% endhint %}

### Parameters

<table><thead><tr><th width="178.33333333333331">Name</th><th width="132">Requirments</th><th width="90">Section</th><th width="94">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-Key</td><td>Required</td><td>Head</td><td>String</td><td>User API key used to authenticate requests</td></tr><tr><td>refresh-token</td><td>Required</td><td>Head</td><td>String</td><td>Token used to generate more JWT’s</td></tr><tr><td>devID</td><td>Required</td><td>Body</td><td>String</td><td>Your developer ID</td></tr></tbody></table>

{% hint style="info" %}
Please note that the following code is *Node.js*
{% endhint %}

```javascript
const url = "https://api.kaedim3d.com/api/v1/refreshJWT"
const headers = {
  "Content-Type": "application/json",
  "X-API-Key": "your_api_key",
  "refresh-token": "your-refresh-token"
}
const body = {
  "devID": "your_dev_id",
}
try {
   fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}
```

{% hint style="info" %}
Please note that the following responses are in *JSON*
{% endhint %}

200 Response

```json
{
    "status": "success",
    "message": "JWT refreshed successfully. Please use the new JWT and devID to authenticate your future requests",
    "jwt": "eyJhaU.....",
    "devID": "609d43109ff0b252cce4bc6e"
}
```

400 Response

```json
{
    "status": "error",
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "message" : "Request failed, please check your api-key and refresh-token and try again"
    "cause": "...."
}
```

### Error Codes

We use normal HTTP codes to indicate the success or failure of your API requests. If your request fails, Kaedim will return an appropriate error message.

<table><thead><tr><th>Field Name</th><th width="183.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>Status</td><td>String</td><td>Short string describing the status of the request. Generally "success" or "error".<br></td></tr><tr><td>Message</td><td>String</td><td>Short human-readable string giving more context on the reason the error occurred.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kaedim3d.com/enterprise-features/custom-integrations/apis/web-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.