# Web API

We wrote an example Python script [here](https://colab.research.google.com/drive/1QREQgxvLKDW30J87MhDufCPRdue6Dnsj?usp=sharing) 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="https://2929718666-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3dfqxWeW1YVSmrxYlvkW%2Fuploads%2FOrawuJUO4YU3GlUr2c1L%2FapiSettings.png?alt=media&#x26;token=71da3a71-d335-4654-8ebc-34183c2daab4" 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](https://docs.kaedim3d.com/creating-assets/input-guidelines "mention")

### **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>