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

An Entity Relationship record is a connection between two Entity records. It can be used to retrieve a hierarchy of records, draw the connections between records in 3D, and to view the hierarchy as a 2D diagram.

It's recommended to read the Relationship Type docs [here](/apirelationtypes) first.

When requesting Entity records using `v3/entity/{entity_id}` or `v3/entity/entities`, you can include the query param `?$expand=relation` to include child Relationship records for the returned Entity records in the response. They will be inside `Bruce/Relations` in the response JSON.

## Relationship requests

Below are the basic requests for managing Relationships.

### Get Entity Relationships

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

**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 | ID of the Entity to get Relationships for. |

**Response**

```typescript
interface IResponse {
    Items: {
        // ID of the parent Entity.
        "Principal.Entity.ID": string;
        // ID of the child Entity.
        "Related.Entity.ID": string;
        // Relationship Type ID.
        "Relation.Type.ID": string;

        // (Optional) ID of the data Entity.
        // The data Entity is where the Relationship attribute data is stored.
        "Data.Entity.ID"?: string;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/relations/";
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 Relationships by Type

```http
GET https://{accountId}.api.nextspace.host/entity/{entity_id}/relations/{type_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. |
| `{entity_id}` | path | yes | ID of the Entity to get Relationships for. |
| `{type_id}` | path | yes | ID of the Relationship Type to get Relationships for. |

**Response**

```typescript
// Same response body as the above get-list.
```

**Javascript example**

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

### Update Relationship

```http
POST https://{accountId}.api.nextspace.host/entity/${parent_id}/otherEntityID/{child_id}/relation/{type_id}/update
```

**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. |
| `{child_id}` | path | yes | ID of the child Entity. |
| `{type_id}` | path | yes | ID of the related Relationship Type. |

**Request body**

```typescript
interface IBody {
    // (Optional) ID of the data Entity.
    // The data Entity is where the Relationship attribute data is stored.
    "Data.Entity.ID"?: string;
}
```

**Response**

```typescript
// Body is a JSON object with the same properties as a single item from the get-list above.
// It returns a single Relationship record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/${parent_id}/otherEntityID/{child_id}/relation/{type_id}/update";
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);
});
```

### Update Relationship

```http
POST https://{accountId}.api.nextspace.host/entity/${parent_id}/otherEntityID/{child_id}/relation/{type_id}/update
```

**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. |
| `{child_id}` | path | yes | ID of the child Entity. |
| `{type_id}` | path | yes | ID of the related Relationship Type. |

**Request body**

```typescript
interface IBody {
    // ID of the data entity.
    // The data Entity is where the Relationship attribute data is stored.
    "Data.Entity.ID"?: string;
}
```

**Response**

```typescript
// Body is a JSON object with the same properties as a single item from the get-list above.
// It returns a single Relationship record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/${parent_id}/otherEntityID/{child_id}/relation/{type_id}/update";
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 Relationships

```http
POST https://{accountId}.api.nextspace.host/entity/${parent_id}/relation/{type_id}/add
```

**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. |
| `{type_id}` | path | yes | ID of the related Relationship Type. |

**Request body**

```typescript
interface IBody {
    // Array of child Entity IDs to create Relationships with.
    // If an existing Relationship exists, nothing occurs for that child.
    "Related.Entity.ID": string[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/${parent_id}/relation/{type_id}/add";
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);
});
```

### Update Relationship

```http
POST https://{accountId}.api.nextspace.host/entity/${parent_id}/otherEntityID/{child_id}/relation/{type_id}/update
```

**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. |
| `{child_id}` | path | yes | ID of the child Entity. |
| `{type_id}` | path | yes | ID of the related Relationship Type. |

**Request body**

```typescript
interface IBody {
    // ID of the data entity.
    // The data Entity is where the Relationship attribute data is stored.
    "Data.Entity.ID"?: string;
}
```

**Response**

```typescript
// Body is a JSON object with the same properties as a single item from the get-list above.
// It returns a single Relationship record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/${parent_id}/otherEntityID/{child_id}/relation/{type_id}/update";
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 Relationships

```http
POST https://{accountId}.api.nextspace.host/entity/{parent_id}/relation/{type_id}/delete
```

**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. |
| `{parent_id}` | path | yes | ID of the parent Entity. |
| `{type_id}` | path | yes | ID of the related Relationship Type. |

**Request body**

```typescript
interface IBody {
    // Array of the child Entity IDs to delete Relationships with.
    "Related.Entity.ID": string[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{parent_id}/relation/{type_id}/delete";
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);
});
```

## Experimental requests

To get the top-level Entity for for a given Entity ID and Relationship Type, you can perform the below request.

### Get top-level Entity for Entity and Relationship Type

```http
GET https://{accountId}.api.nextspace.host/entity/{entity_id}/relation/{type_id}/top
```

**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 | ID of the Entity to get Relationships for. |
| `{type_id}` | path | yes | ID of the Relationship Type to get Relationships for. |

**Response**

```typescript
interface IResponse {
    // ID of the top-level Entity for the provided Relationship information.
    // Legacy naming as this is related to a deprecated prototype/instance feature.
    "InstanceEntityID": string;

    // Path of Entity IDs from the top-level Entity to the provided Entity.
    // Currently, circular paths can cause issues in other requests.
    // So if this has recurring IDs (or is very long, eg: >30 length),
    // then it's recommended to avoid requesting a tree diagram for this Relationship.
    "Path": string[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/relation/{type_id}/top";
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);
});
```

Here is how you can request a full Entity tree from a given starting Entity. Avoid calling this request for circular paths, which can be detected with the above get-top request.

### Get Entity hierarchy

```http
GET https://{accountId}.api.nextspace.host/experimental/hierarchy/{entity_id}?HierarchyTypeID={type_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. |
| `{entity_id}` | path | yes | ID of the Entity to get Relationships for. |
| `HierarchyTypeID={type_id}` | query | yes | ID of the Relationship Type to get Relationships for. |

**Response**

```typescript
interface IResponse {
    Root: INode;
}

interface INode {
    // ID of the Entity.
    ID: string;
    // ID of the Relationship Type.
    "Type.ID": string;
    // Array of child Entities (if any).
    "Children": ITreeResNode[] | null;
}
```

**Javascript example**

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

---

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