---
title: "Entity LODs (representations)"
section: "API Reference"
route: /apientitylod
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Entity LODs (representations)

An Entity LOD (level of detail) is a Client File that represents an Entity.

LODs have categories which describe what the LOD is for. Our most common category is GLB which is used for GLB and GLTF representations that are supported in CesiumJS (our default renderer).

LODs have numeric levels within their LOD Category, where 0 is the highest quality.

You can choose to represent your Entity in any format you choose, for example you can have an SVG representation of an Entity that you display in your app.

Entity Types can also have LODs assigned to them to act as defaults when an Entity one is unavailable. This is commonly used for large sets of repeated graphics. See more [here](/apientitytypelod)

You can read about how to create file download links for LODs here: [Client and temp files](/apiclientfile).

## LOD Category requests

Below are the basic requests for managing LOD Category records.

### Get LOD Categories

```http
GET https://{accountId}.api.nextspace.host/lodCategories
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Response**

```typescript
interface IResponse {
    Items: {
        // Description of the category.
        Description?: string;
        // Unique identifier for the category.
        // This is case-insensitive.
        Key: string;
        // Name of the category.
        Name: string;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/lodCategories";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get LOD Category by Key

```http
GET https://{accountId}.api.nextspace.host/lodCategory/{key}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{key}` | path | yes | LOD Category key to retrieve the record for. |

**Response**

```typescript
interface IResponse {
    // Description of the category.
    Description?: string;
    // Unique identifier for the category.
    // This is case-insensitive.
    Key: string;
    // Name of the category.
    Name: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/lodCategory/{key}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Create/Update LOD Category

```http
POST https://{accountId}.api.nextspace.host/lodCategory/{key}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{key}` | path | yes | LOD Category Key to create or update. |

**Response**

```typescript
interface IRequest {
    // Description of the category.
    Description?: string;
    // Unique identifier for the category.
    // This is case-insensitive.
    Key: string;
    // Name of the category.
    Name: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/lodCategory/{key}";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete LOD Category

```http
DELETE https://{accountId}.api.nextspace.host/lodCategory/{key}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{key}` | path | yes | LOD Category Key to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/lodCategory/{key}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Get Entity LODs

This request will not overlay an Entity Type's LODs. It only returns LODs directly associated with the Entity itself.

### Get Entity LODs

```http
GET https://{accountId}.api.nextspace.host/entity/{entity_id}/lods
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{entity_id}` | path | yes | Entity ID to retrieve LODs for. |

**Response**

```typescript
interface IResponse {
    Items: {
        // ID of the related Client File record.
        "ClientFile.ID": string;
        // ID of the related Entity record.
        "Entity.ID": string;
        // Key of the LOD Category.
        "LODCategory.Key": string;
        // Level of detail. 0 is the highest.
        Level: number;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/lods";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Get Entity LODs (with defaults)

This an optimized rendering request that will return the "best" LOD per Entity. It will return an Entity Type LOD if no Entity LOD is available.

### Get Entity LODs (with defaults)

```http
GET https://{accountId}.api.nextspace.host/entity/getlods
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IRequest {
    // Whether to use strict mode.
    // When false, a lower quality LOD (higher level) is returned if the requested level is not available.
    "strict": boolean;
    "Items": {
        // ID of the related Entity record.
        "entityId": string,
        // ID of the related LOD Category record.
        "categoryId": string,
        // LOD group within its Entity Type.
        "group"?: string,
        // Level of detail. 0 is the highest.
        "level"?: number
    }[];
}
```

**Response**

```typescript
interface IResponse {
    Items: {
        // ID of the LOD's Client File.
        clientFileId: string;
        // ID of the related Entity record.
        entityId: string;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/getlods";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Delete Entity LODs

Unlike typical 'unlinking' deletions, this request **will** delete the related Client File records.
This is subject to change as LOD Client Files have a background cleaner that will delete them if they are not in use already.

### Delete Entity LODs

```http
DELETE https://{accountId}.api.nextspace.host/entity/{entity_id}/deleteLODs
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{entity_id}` | path | yes | Entity ID to delete LODs for. |

**Request body**

```typescript
interface IRequest {
    Items: {
        // ID of the related LOD Category record.
        "LODCategory.Key": string;
        // Level of detail. 0 is the highest.
        "Level": number;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/deleteLODs";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Create Entity LOD

You can request to attach a Client File record to an Entity as a LOD.
It is recommended to read the [Client and temp files](/apiclientfile) documentation first.

### Create Entity LOD

```http
POST https://{accountId}.api.nextspace.host/entity/{entity_id}/lod/{category_key}/{level}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{entity_id}` | path | yes | Entity ID to create the LOD for. |
| `{category_key}` | path | yes | LOD Category key to assign the LOD to. |
| `{level}` | path | yes | Level of detail. 0 is the highest. |

**Request body**

```typescript
interface IRequest {
    "ClientFile.ID": string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/lod/{category_key}/{level}";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apientitylod