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

An Entity Tag is a way to add different categories for an Entity to improve searchability, and to add access restrictions.

If you see references to "Layers" in documentation, that is a legacy term for Tags.

## Data model

Below is a basic data model for a Tag record.

When further documentation refers to `ITag` or just a Tag record, you can reference this data model.

```typescript
interface ITag {
    // ID of the Tag.
    // To create a new Tag, don't specify the ID.
    ID: number;
    // Human readable name of the Tag.
    Name: string;
    // Description of the Tag.
    Description?: string;
    // If tag access (and tagged Entity access) should be restricted.
    // When a Tag is restricted a user must have the "Layer_<tag_id>" permission to view the Tag/Entity.
    IsAccessRestricted?: boolean;
    // Colour of the tag to use when styling Entities or displaying a Tag icon.
    Color?: string;
    // Parent tag ID.
    // Purely for organizational purposes.
    "Parent.Layer.ID"?: number;
}
```

## Entity Tag requests.

Below are the basic requests for managing Tag records.

### Get Tags

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

**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: ITag[];
}
```

**Javascript example**

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

```http
GET https://{accountId}.api.nextspace.host/layer/{layer_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. |
| `{layer_id}` | path | yes | No description available. |

**Response**

```typescript
// Response is the Tag record directly.
// See the 'Data model' section for the structure.
```

**Javascript example**

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

### Get Tags by IDs

```http
POST https://{accountId}.api.nextspace.host/layers/get
```

**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 {
    "layerIds": number[];
}
```

**Response**

```typescript
interface IResponse {
    Items: ITag[];
}
```

**Javascript example**

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

### Create / Update Tag

```http
POST https://{accountId}.api.nextspace.host/layer/{layer_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>".
- 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. |
| `{layer_id}` | path | no | ID of the Tag. To create a new Tag, don't specify the ID. |

**Response**

```typescript
// Response is the Tag record directly.
// See the 'Data model' section for the structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/layer/{layer_id}";
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 Tag

```http
DELETE https://{accountId}.api.nextspace.host/layer/{layer_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>".
- 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. |
| `{layer_id}` | path | yes | ID of the Tag to delete. |

**Javascript example**

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

## Assigning Tags

To update an Entity's Tags you update its `Bruce/Layer.ID` field. It is an array of Tag IDs.

```json
{
    "Bruce": {
        "Layer.ID": [1, 2, 3]
    }
}
```

You can use our typical Create/Update Entity requests to update this value. See [Entities](/apientities).

Additionally, we have DataLab actions for adding/removing and setting Tags for Entities based on a query. See [DataLab actions](/apidatalabactions).

---

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