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

A Change Set is a bundle of proposed changes to Entities, their relationships, representations and Assemblies, held back until someone reviews and commits it. Nothing in a Change Set touches your data until it is committed.

Change Sets are most often created by an import run in staged mode, so a large update can be checked in Operator or Navigator before it lands. You can also build one yourself by adding change items to it.

This article will cover how to manage Change Sets and their items, and how to commit, reject and export them.

## Data model

Below is the core data model for a Change Set. The changes themselves are separate item records, covered in the Change Sets: Items section below.

```typescript
interface IChangeSet {
    // Unique ID for the Change Set.
    // Exclude this value for new records.
    ID?: number;
    // Description of the change. Imports fill this with the import and file name.
    Description: string;
    // See the statuses section below. "Error" is reserved and not set by the API.
    // Default is "Uncommitted".
    Status?: "Uncommitted" | "Committed" | "Cancelled" | "Error";
    // ID of the user who created the record, set by the API.
    "Created.ByUser.ID"?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
    // What the requesting user can do with Change Sets.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    Permission?: string;

    // Only returned when "Count" is expanded.
    // Item counts by action, across Entity, relationship and representation changes.
    Count?: IChangeCount;
    // Only returned when "CountByConcept" is expanded on a single record.
    // The same counts for each concept the set has items of, keyed by concept code.
    CountByConcept?: { [concept: string]: IChangeCount };

    // Only returned on a single record.
    // IDs that help show the set in a scene, including the preview Tilesets made for it.
    Context?: {
        "EntityType.ID"?: string[];
        "RootEntity.ID"?: string[];
        "Tileset.ID"?: string[];
    };
    // Only returned on a single record.
    // The latest pending action run against the set, such as its import or commit.
    "PendingAction.ID"?: number;
    PendingAction?: any;
}

interface IChangeCount {
    Create: number;
    Update: number;
    Delete: number;
}
```

## Statuses

A new Change Set is "Uncommitted", and only an Uncommitted set can be committed. From there:

| Status | How it is reached | Can change to |
| --- | --- | --- |
| "Uncommitted" | A new set, or reopening a Cancelled set. | "Cancelled" by rejecting it, or "Committed" by committing it. |
| "Committed" | The commit request finishing. | Nothing. A committed set is final. |
| "Cancelled" | The reject request, or saving the status directly. | "Uncommitted", to reopen it. |

Moving a set out of "Uncommitted" deletes the preview Tilesets made for it.

## Staging an import

Assembly, CSV, GeoJSON, JSON and XLSX imports can stage their changes instead of applying them. Add "ChangeSet": true to the import settings. The import creates a new Change Set, and its pending action result includes the set's ID.

```typescript
// Added to the import settings.
{
    "ChangeSet": true
}

// Part of the import's pending action result.
{
    "ChangeSet.ID": 42
}
```

You can read about each import in [Import Assemblies](/apiimportassembly), [Import CSV](/apiimportcsv), [Import GeoJSON](/apiimportgeojson) and [Import JSON](/apiimportjson), and about pending actions in [Pending Actions](/apipendingaction).

## Requesting records

The list is paged, newest first. The first page includes the total count. Set both "PageSize" and "PageIndex" to -1 to get only the count.

### Get a list of Change Sets

```http
GET https://{accountId}.api.nextspace.host/v3/changes?PageSize={50}&PageIndex={0}&Expand={Count}
```

**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. |
| `PageSize={50}` | query | no | How many records to return per page. Default is 50. |
| `PageIndex={0}` | query | no | Which page to return, starting from 0. |
| `Expand={Count}` | query | no | Include each set's item counts. |

**Response**

```typescript
interface IResponse {
    Items: IChangeSet[];
    // Only included on the first page.
    TotalCount?: number;
}
```

**Javascript example**

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

```http
GET https://{accountId}.api.nextspace.host/v3/change/{change_id}?Expand={Count,CountByConcept}
```

**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. |
| `{change_id}` | path | yes | The ID of the Change Set to get. |
| `Expand={Count,CountByConcept}` | query | no | Include the item counts, the counts per concept, or both. |

**Response**

```typescript
// The response is the Change Set record directly, including "Context" and the latest pending action.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/change/{change_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 Change Set by setting the ID as '0', or update one by its ID. Changing "Status" follows the rules in the statuses section above. A set cannot be saved as "Committed", use the commit request instead.

### Create or update Change Set

```http
POST https://{accountId}.api.nextspace.host/v3/change/{change_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. |
| `{change_id}` | path | yes | The ID of the Change Set to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Change Set JSON as specified at the top of the article.
```

**Example request body**

```json
{
    "Description": "Rename the north site valves"
}
```

**Response**

```typescript
// The response is the Change Set record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/change/{change_id}";
const method = "post";
const token = "your-token";
const body = {
    "Description": "Rename the north site valves"
};

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);
});
```

## Committing and rejecting

Committing applies every item in the set, as a background job. Entity Type changes are applied first, then Entities, relationships, representations and Assemblies. Once done, the set is marked "Committed", Tilesets showing the changed Entities are regenerated, and the preview Tilesets are deleted.

The response gives the job's pending action ID, which you can follow until it finishes. Only one commit of a set can run at a time.

### Commit Change Set

```http
POST https://{accountId}.api.nextspace.host/v3/change/{change_id}/commit
```

**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. |
| `{change_id}` | path | yes | The ID of the Uncommitted Change Set to commit. |

**Response**

```typescript
interface IResponse {
    PendingActionID: number;
}
```

**Javascript example**

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

Rejecting a set marks it "Cancelled" and deletes its preview Tilesets. A committed set cannot be rejected.

### Reject Change Set

```http
POST https://{accountId}.api.nextspace.host/v3/change/{change_id}/reject
```

**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. |
| `{change_id}` | path | yes | The ID of the Change Set to reject. |

**Response**

```typescript
// The response is the Change Set record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/change/{change_id}/reject";
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 a record

Deleting a Change Set also deletes all its items and its preview Tilesets. Changes already committed are not undone.

### Delete Change Set

```http
DELETE https://{accountId}.api.nextspace.host/v3/change/{change_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. |
| `{change_id}` | path | yes | The ID of the Change Set to delete. |

**Javascript example**

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

## Change Sets: Items

Each item is one proposed change. Its concept says what kind of record it changes, its action says whether it creates, updates or deletes it, and its data holds the details.

```typescript
interface IChangeItem {
    // Unique ID for the item.
    // Exclude this value for new records.
    ID?: number;
    // ID of the Change Set the item belongs to.
    "Change.ID": number;
    // C = create, U = update, D = delete.
    Action: "C" | "U" | "D";
    /**
     * What kind of record the item changes.
     *
     * E = Entity.
     * ER = Entity relationship.
     * EL = Entity representation (LOD).
     * A = Assembly. Only create is supported.
     * ET = Entity Type. These are staged by imports and listed alongside, but cannot be written here.
     */
    Concept: "E" | "ER" | "EL" | "A" | "ET";
    // The details, based on the concept. See below.
    Data: any;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

Below is the data each concept reads when the set is committed.

```typescript
// E: Entity.
interface IEntityChangeData {
    "Entity.ID": string;
    // Required when creating.
    "EntityType.ID"?: string;
    // The Entity's new attributes and Bruce values, such as name, location and transform.
    // You can read about the Entity structure in Entities.
    Entity?: any;
    // Layer IDs to set on the Entity.
    "Layer.ID"?: number[];
    // For updates. Attribute paths to remove from the Entity.
    "Entity.RemovedAttributes"?: string[];
}

// ER: Entity relationship.
interface IRelationChangeData {
    "Principal.Entity.ID": string;
    "Relation.Type.ID": string;
    "Other.Entity.ID": string;
    "Dimension.ID"?: number;
    "DisplayOrder"?: number;
    // Entity holding extra data about the relationship.
    "Data.Entity.ID"?: string;
    Collapsed?: boolean;
}

// EL: Entity representation (LOD).
// A delete removes every representation of the Entity.
interface ILodChangeData {
    "Entity.ID": string;
    "LODCategory.Key"?: string;
    Level?: number;
    Group?: string;
    ScaleToMeter?: number;
    "ClientFile.ID"?: string;
    "Geometry.ID"?: number;
}

// A: Assembly. Skipped when the root Entity already has an Assembly.
interface IAssemblyChangeData {
    "RootEntity.ID": string;
    // Default is "Unnamed Assembly".
    Name?: string;
    "RelationType.ID"?: string;
    "FileImport.ID"?: number;
    "ParentAssembly.ID"?: number;
}
```

You can read about the records these change in [Entities](/apientities), [Relationships](/apirelations), [Entity LODs](/apientitylod) and [Import Assemblies](/apiimportassembly).

### Requesting items

Items are paged and can be filtered by concept and action. Prefix a filter with "!" to exclude it instead, such as "!D" for everything but deletes.

"IndexOf" finds where an Entity's first item sits in the list, so a paged review can turn to the page holding it.

### Get Change Set items

```http
GET https://{accountId}.api.nextspace.host/v3/change/{change_id}/items?PageSize={50}&PageIndex={0}&Concept={concept}&Action={action}&EntityID={entity_id}&IndexOf={entity_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. |
| `{change_id}` | path | yes | The ID of the Change Set to get the items of. |
| `PageSize={50}` | query | no | How many items to return per page. Default is 50. |
| `PageIndex={0}` | query | no | Which page to return, starting from 0. Set both to -1 to get only the count. |
| `Concept={concept}` | query | no | Only items of this concept, such as E. Prefix with ! to exclude it. |
| `Action={action}` | query | no | Only items with this action, such as D. Prefix with ! to exclude it. |
| `EntityID={entity_id}` | query | no | Only items about this Entity. |
| `IndexOf={entity_id}` | query | no | Instead of a page, return the position of this Entity's first item. Cannot be combined with EntityID or an excluded concept. |

**Response**

```typescript
interface IResponse {
    // The Change Set the items belong to.
    Change: IChangeSet;
    Items: IChangeItem[];
    // Only included on the first page.
    TotalCount?: number;
}

// The response when "IndexOf" is used.
interface IIndexOfResponse {
    Change: IChangeSet;
    // Position of the Entity's first item, starting from 0, or -1 when no item names it.
    Index: number;
    // The concept the position is counted within. Absent when Index is -1.
    Concept?: string;
}
```

**Javascript example**

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

### Writing items

You can create an item by setting the ID as '0', or update one by its ID. To write many at once, use the batch request, where items with an ID are updated and items without one are created.

### Create or update item

```http
POST https://{accountId}.api.nextspace.host/v3/change/{change_id}/item/{item_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. |
| `{change_id}` | path | yes | The ID of the Change Set the item belongs to. |
| `{item_id}` | path | yes | The ID of the item to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the item JSON as specified above.
```

**Example request body**

```json
{
    "Action": "U",
    "Concept": "E",
    "Data": {
        "Entity.ID": "your-entity-id",
        "Entity": {
            "Bruce": {
                "Name": "Valve 12"
            }
        }
    }
}
```

**Response**

```typescript
// The response is the item record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/change/{change_id}/item/{item_id}";
const method = "post";
const token = "your-token";
const body = {
    "Action": "U",
    "Concept": "E",
    "Data": {
        "Entity.ID": "your-entity-id",
        "Entity": {
            "Bruce": {
                "Name": "Valve 12"
            }
        }
    }
};

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 or update several items

```http
POST https://{accountId}.api.nextspace.host/v3/change/{change_id}/items
```

**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. |
| `{change_id}` | path | yes | The ID of the Change Set the items belong to. |

**Request body**

```typescript
interface IBody {
    Items: IChangeItem[];
}
```

**Response**

```typescript
interface IResponse {
    // Number of new items created.
    Created: number;
    // Number of existing items updated.
    Updated: number;
}
```

**Javascript example**

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

```http
DELETE https://{accountId}.api.nextspace.host/v3/change/{change_id}/item/{item_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. |
| `{change_id}` | path | yes | The ID of the Change Set the item belongs to. |
| `{item_id}` | path | yes | The ID of the item to delete. |

**Javascript example**

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

## Change Sets: Export

You can export a Change Set as a spreadsheet, for example to share it for sign-off. The export runs as a background job, and its pending action result holds a temp file ID and a download URL once it finishes. You can read about temp files in [Client and temp files](/apiclientfile).

### Export Change Set

```http
POST https://{accountId}.api.nextspace.host/v3/change/{change_id}/export
```

**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. |
| `{change_id}` | path | yes | The ID of the Change Set to export. |

**Request body**

```typescript
interface IBody {
    // The file format. Only "XLSX" is supported.
    Type: "XLSX";
}
```

**Example request body**

```json
{
    "Type": "XLSX"
}
```

**Response**

```typescript
interface IResponse {
    "PendingAction.ID": number;
    // Request URL for the pending action, returning its result as JSON.
    "PendingAction.URL": string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/change/{change_id}/export";
const method = "post";
const token = "your-token";
const body = {
    "Type": "XLSX"
};

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