---
title: "Markup"
section: "API Reference"
route: /apimarkup
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Markup

Markup is the set of text boxes, callouts, lines, shapes and sections drawn over a scene in Navigator. A bookmark keeps its own markup within its settings, and a Project View can hold markup shared across its bookmarks.

Markup records store markup on its own, outside of any bookmark. Today they hold the templates in Navigator's markup panel, which users save from one element and reuse across bookmarks and Project Views.

This article will cover how to manage Markup records and how a template is laid out. The markup content itself, and where each kind of markup is stored, is described in [JSON: Markup](/formatjsonmarkup).

## Data model

Below is the core data model for a Markup record. You can manage a record without populating the content.

```typescript
interface IMarkupRecord {
    // Unique ID for the Markup record.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 100 characters.
    Name?: string;
    // Description of what the markup is for.
    Description?: string;
    // If true then the record is offered as a template in Navigator's markup panel.
    // Default is false.
    IsTemplate?: boolean;
    // The markup content.
    // See the JSON: Markup file format for the structure.
    MarkupContent?: IMarkup;
    // ID of the Markup record this one was copied from.
    "Original.UI.Markup.ID"?: number;
    // ID of a Client File holding a thumbnail image of the markup.
    "Thumbnail.ClientFile.ID"?: string;
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
    // ID of the user who created the record, set by the API.
    "Created.ByUser.ID"?: string;
    // ISO 8601 date time string, set by the API.
    "Created.DateTime"?: string;
}
```

## Templates

A template is a Markup record with "IsTemplate" set to true. Its content holds the element the user saved, which we call the lead element, followed by anything that has to travel with it. For example a callout box is saved with the line that points to it.

Elements are read in the order "divs", "vectors" then "cesiumObjects", and the first one found is the lead element. Lines that travel with a box reference it by id through their snaps, so keep those ids in step when writing a template by hand.

```typescript
// How a template's MarkupContent is read.
interface ITemplateContent {
    // The lead element is the first div when there is one.
    divs?: IDiv[];
    // Lines saved alongside the lead element, such as a callout's connector.
    vectors?: (ILine | IPaint)[];
    // Elements placed in the scene, plus labels, dialogs and groups.
    cesiumObjects?: (IPolygon | IPolyline | ICircle | IRectangle | ISphere |
                     ISection | ISectionBox | ITerrainSection | IElementGroup | ILabels | INavDialog)[];
}
```

When a user places a template, each element is copied with a new id. The copies remember where they came from, so the template's look can be applied again later.

```typescript
// Added to each element placed from a template, alongside its own settings.
interface ITemplateInstance {
    // ID of the Markup record the element was placed from.
    markupId: number;
    // ID of the matching element within the template's content.
    templateKey: string;
}
```

Applying a template to an element that is already placed copies its look, such as colours, borders and fonts, cell by cell. The element keeps its own position, size, text and rows. This works when the element has the same rows and cells as the template, or when the template has a single cell.

Here is a template holding a single box with a title row and a body row.

```typescript
{
    Name: "Warning box",
    IsTemplate: true,
    MarkupContent: {
        divs: [
            {
                id: "m4q7t0w3z6ab",
                type: "default",
                borderColor: "rgba(255, 127, 46, 1)",
                borderWidth: 2,
                borderRadius: 8,
                contentRows: [
                    {
                        height: 40,
                        items: [
                            {
                                contentType: "DEFAULT",
                                text: "Warning",
                                width: 100,
                                backgroundColor: "rgba(255, 127, 46, 1)",
                                fontColor: "white",
                                fontSize: 16,
                                textAlign: "left",
                                verticalAlign: "center"
                            }
                        ]
                    },
                    {
                        height: 60,
                        items: [
                            {
                                contentType: "DEFAULT",
                                text: "Details here",
                                width: 100,
                                backgroundColor: "white",
                                fontColor: "black",
                                fontSize: 14,
                                textAlign: "left",
                                verticalAlign: "top"
                            }
                        ]
                    }
                ]
            }
        ],
        vectors: [],
        cesiumObjects: []
    }
}
```

## Requesting records

You can request a list of all Markup records or an individual one. Both include the markup content, so filter the list by "IsTemplate" when you only want templates.

### Get a list of Markup records

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

**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 {
    // Array of Markup records.
    // See the data model above for the record structure.
    Items: IMarkupRecord[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.markups";
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 Markup record by ID

```http
GET https://{accountId}.api.nextspace.host/ui.markup/{markup_id}
```

**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. |
| `{markup_id}` | path | yes | The ID of the Markup record to get. |

**Response**

```typescript
// The response is the Markup record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.markup/{markup_id}";
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 and update records

You can create a record by performing a POST request to the same URL as the GET. If you specify the ID as '0' then it'll create a new record and return it. If you specify an existing ID then it'll update the record and return it.

When updating, only the properties you include are changed. The markup content is replaced as a whole, so send all of it rather than only the elements that changed.

### Create or update Markup record

```http
POST https://{accountId}.api.nextspace.host/ui.markup/{markup_id}
```

**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. |
| `{markup_id}` | path | yes | The ID of the Markup record to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Markup record JSON as specified at the top of the article.
```

**Example request body**

```json
{
    "Name": "My new template",
    "IsTemplate": true,
    "MarkupContent": {
        "divs": [],
        "vectors": [],
        "cesiumObjects": []
    }
}
```

**Response**

```typescript
// The response is the Markup record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.markup/{markup_id}";
const method = "post";
const token = "your-token";
const body = {
    "Name": "My new template",
    "IsTemplate": true,
    "MarkupContent": {
        "divs": [],
        "vectors": [],
        "cesiumObjects": []
    }
};

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 a record

We don't provide any bulk deletion but you can delete by record ID. Deleting an ID that does not exist still succeeds.

Elements already placed from a deleted template are not removed. They keep their look but can no longer have the template applied again.

### Delete Markup record

```http
DELETE https://{accountId}.api.nextspace.host/ui.markup/{markup_id}
```

**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. |
| `{markup_id}` | path | yes | The ID of the Markup record to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.markup/{markup_id}";
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);
});
```

---

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/apimarkup
