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

An Entity scenario is alternative state for the Entity to be in. It is a way to manage simulations where an Entity needs to take on a temporary state.

## Creating a 'Scenario' Entity

If you update an Entity record and include the `Scenario` value, then the primary record is not touched. It will create/update the related scenario data instead.

You can alternatively specify the scenario ID or Key in the query param, which will override any values supplied in the body.

You must be updating an existing Entity record.

### Create/Update one 'Scenario' Entity

```http
POST https://{accountId}.api.nextspace.host/v3/entity?Scenario={scenario}
```

**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. |
| `Scenario={scenario}` | query | no | Scenario ID or key to reference. Can be supplied here, or within the Entity data. |

**Request body**

```typescript
interface IPostBody {
    "Bruce": {
        "ID": "your-entity-id",
        // Can be supplied here, or through the query param.
        "Scenario": "your-scenario-key-or-id"
    },
    "some-key": "some-value"
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/entity";
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 multiple 'Scenario' Entities

```http
POST https://{accountId}.api.nextspace.host/v3/entities?Scenario={scenario}
```

**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. |
| `Scenario={scenario}` | query | no | Scenario ID or key to reference. Can be supplied here, or within the Entity data. If supplied here then it will override any individually specified values. |

**Request body**

```typescript
interface IPostBody {
    "Items": [
        {
            "Bruce": {
                "ID": "your-entity-id",
                // If the query param is supplied, then this value will be overridden.
                "Scenario": "your-scenario-key-or-id"
            }
        },
        {
            "Bruce": {
                "ID": "your-entity-id-2"
                // Can omit the Scenario if the query param is supplied.
            }
        }
    ]
}
```

**Javascript example**

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

## Getting a 'Scenario' Entity

You can perform our typical requests and include either `Scenario=blah` in the query or body (depending on if you're doing a GET or POST search).

The scenario data is included after the query resolves, so your filters will not apply against the scenario! This is something we're looking to improve.

### Get a 'Scenario' Entity

```http
GET https://{accountId}.api.nextspace.host/v3/entity/{entity_id}?Scenario={scenario}
```

**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. |
| `Scenario={scenario}` | query | no | Scenario ID or key to get. |

**Response**

```typescript
interface IResponse {
    "Bruce": {
        "CreatedBy.User.ID": "dummy",
        "Created": "some-date-time-string",
        "EntityType.ID": "some-entity-type-id",
        "ID": "some-entity-id",
        // Outline on what parts of the Entity were loaded from where.
        // This is a preview on what properties are available (focused on Scenarios here).
        "Outline"?: {
            // Indicates that this is the baseline source of Entity data.
            // If true, then any attributes not specified by another source are assumed to be from this one.
            "Baseline"?: boolean;
            // Human readable name of the source.
            "Source.Name": string;
            // Related Scenario record if any.
            // This is the scenario ID or key. Typically the Key.
            "Scenario"?: string | number;
            // DateTime representing the time of the record (if any).
            "DateTime"?: string;
            // Indicates that this source is editable.
            // When false, inputs for the related attribute are disabled.
            "Editable": boolean;
            // Array of attribute paths that were loaded from this source.
            // If Baseline=true, then all attributes that weren't specified are loaded from this source.
            "Attribute"?: string[];
        }[]
    },
    "some-key": "some-value"
}
```

**Javascript example**

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

### Get multiple 'Scenario' Entities

```http
GET https://{accountId}.api.nextspace.host/v3/entities?Type={entity_type_id}&Scenario={scenario}
```

**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. |
| `Type={entity_type_id}` | query | no | Example filter, in this case an Entity Type ID to filter by. |
| `Scenario={scenario}` | query | no | Scenario ID or key to get. |

**Javascript example**

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

## Getting a 'Scenario' record

You can get the plain records directly as well. This means it won't include our typical internal `Bruce` data.

Note that this uses the same technology as the historic-records so until a v3 request is available, some terminology may be the same.

### Get 'Scenario' records

```http
GET https://{accountId}.api.nextspace.host/v1/entity/historicData?Scenario={scenario}&entityId={entity_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. |
| `Scenario={scenario}` | query | yes | Scenario ID or key to get. |
| `entityId={entity_id}` | query | yes | Entity ID to retrieve. Specify this query param multiple times to get multiple records. |

**Javascript example**

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

## Deleting 'Scenario' Entity records

If an Entity is deleted, the related scenario data is also deleted.
if the scenario is deleted, all scenario data related to it is deleted.

Note that this uses the same technology as the historic-records so until a v3 request is available, some terminology may be the same.

### Delete 'Scenario' records

```http
DELETE https://{accountId}.api.nextspace.host/v1/entity/historicData?Scenario={scenario}&entityId={entity_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. |
| `Scenario={scenario}` | query | yes | Scenario ID or key to get. |
| `entityId={entity_id}` | query | yes | Related Entity ID. Specify this query param multiple times to delete multiple records. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v1/entity/historicData";
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/apientityscenarios