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

If you've finished reading the DataLab queries documentation, you're ready to start performing actions against the response data.

An action is a server-side job that will be performed against all found Entities for your query. This allows you to perform bulk operations without having to iterate over the results in your client code.

Performing an action will return a `PendingAction.ID` for you to monitor. Refer to the Pending Action documentation for help.

Not all actions are currently documented. Please contact support if you want more information about any actions, including those available in Operator but not documented here.

## Action: Set attribute value

### DataLab action | Set attribute value

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "set-attribute";
        // Performs some additional validation during the process based on the supplied value.
        // This will default to 'string' when unspecified.
        "AttributeType": "string" | "integer" | "double" | "datetime";
        // This is a Nextspace path string.
        // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
        "Path": string;
        // Value to set.
        "Value": any;
    }
}
```

**Response**

```typescript
interface IResponse {
    // ID of the Pending Action to monitor.
    ID: number;
}
```

**Javascript example**

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

## Action: Update Tags

### DataLab action | Update Tags

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**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 IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "layer";
        "Layer": {
            // Tags IDs.
            "OperandA": [1, 2, 3],
            // Operation we're performing.
            // 'add' will add the Tags to the Entity.
            // 'remove' will remove the Tags from the Entity.
            // 'set' will replace the Tags on the Entity with the supplied tags.
            "Operator": "add" | "remove" | "set";
        }
    }
}
```

**Javascript example**

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

## Action: Create Entity Attachments

Attach an existing file to the selected Entities. This will not duplicate the file in the File Store.

### DataLab action | Attach file

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "attachclientfile";
        "AttachClientFile": {
            // ID of the file to attach.
            "ClientFile.ID": string;
            // Destination Attachment Type ID to attach the file to.
            "AttachmentType.ID": string;
            // Optional grouping within the related Attachment Type.
            // This is useful to further filter attachments within the same group.
            // Pass an empty string or null if you don't want to group the attachment.
            "Group": string;
        }
    }
}
```

**Javascript example**

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

## Action: Export JSON

Export the found Entities and related records into a series of JSON files zipped together.

### DataLab action | Export JSON

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "export-json";
        // Optional expand property to expand additional data to the export.
        // Some options are "Attachment", "Tag", "LOD", "Relation", "EntityType".
        // Comma-separate if you want to do multiple, eg: "Attachment,Tag".
        "Expand"?: string;
        // Optional Scenario ID or Key to use for the export.
        // This will request the Scenario Entity data (if available) for the Entities.
        "Scenario?: string | number;
    }
}
```

**Javascript example**

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

## Action: Export CSV

### DataLab action | Export CSV

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "export-csv";
        // ID of the Entity Type to reference for the schema definition.
        // Schema attributes marked as important/pinned will be included in the CSV.
        // The ID of the selection does not need to match this Type, however the schema should be compatible so you don't get empty rows.
        "EntityTypeID": string;
    }
}
```

**Javascript example**

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

## Action: Delete Entities

### DataLab action | Delete Entities

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "delete";
    }
}
```

**Javascript example**

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

## Action: Delete Relationships

This action will delete Entity Relationships where the found Entities are the parent.

### DataLab action | Delete Relationships

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "delete";
        // The ID of the Relation Type to delete.
        "RelationType.ID": string;
    }
}
```

**Javascript example**

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

## Action: Data Transformation

You can apply a data transformation process against each found Entity by creating a transformation record and applying it to an action.

We'll briefly cover the basic CRUD of these records, then show an example action using them.

### Get Transformation records

```http
GET https://{accountId}.api.nextspace.host/entityType/{type_id}/dataTransforms
```

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

**Response**

```typescript
interface IResponse {
    Items: {
        // ID of the transformation.
        // This is auto-generated for new records.
        "ID": number;
        // Human-readable name of the transformation.
        "Name": string;
        // Human-readable description of the transformation.
        "Description"?: string;
        // The ID of the Entity Type this transformation is for.
        "EntityType.ID": string;
        // Data Mapping to apply between the existing data to the newly saved data.
        // You have only to specify connections that you want changed.
        // See data mapping documentation for more information.
        "DataMapping": IDataMapping;
    }[];
}
```

**Javascript example**

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

```http
GET https://{accountId}.api.nextspace.host/entityType/{type_id}/dataTransform/{transform_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. |
| `{type_id}` | path | yes | The ID of the Entity Type to get the transformation for. |
| `{transform_id}` | path | yes | The ID of the transformation to get. |

**Response**

```typescript
interface IResponse {
    // ID of the transformation.
    // This is auto-generated for new records.
    "ID": number;
    // Human-readable name of the transformation.
    "Name": string;
    // Human-readable description of the transformation.
    "Description"?: string;
    // The ID of the Entity Type this transformation is for.
    "EntityType.ID": string;
    // Data Mapping to apply between the existing data to the newly saved data.
    // You have only to specify connections that you want changed.
    // See data mapping documentation for more information.
    "DataMapping": IDataMapping;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{type_id}/dataTransform/{transform_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/Update Transformation record

```http
DELETE https://{accountId}.api.nextspace.host/entityType/{type_id}/dataTransform/{transform_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. |
| `{type_id}` | path | yes | The ID of the Entity Type to create/update the transformation for. |
| `{transform_id}` | path | no | The ID of the transformation to update, don't specify to create a new transformation. |

**Request body**

```typescript
interface IResponse {
    // ID of the transformation.
    // This is auto-generated for new records.
    "ID"?: number;
    // Human-readable name of the transformation.
    "Name": string;
    // Human-readable description of the transformation.
    "Description"?: string;
    // The ID of the Entity Type this transformation is for.
    "EntityType.ID": string;
    // Data Mapping to apply between the existing data to the newly saved data.
    // You have only to specify connections that you want changed.
    // See data mapping documentation for more information.
    "DataMapping": IDataMapping;
}
```

**Javascript example**

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

### Delete Transformation by ID

```http
DELETE https://{accountId}.api.nextspace.host/entityType/{type_id}/dataTransform/{transform_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. |
| `{type_id}` | path | yes | The ID of the Entity Type to delete the transformation for. |
| `{transform_id}` | path | yes | The ID of the transformation to delete. |

**Javascript example**

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

Here is how you can apply a transformation to an action:

### DataLab action | Data transformation

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/takeAction
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    "PrimarySelection": {
        "Items": any[];
    }
    "Action": {
        "ActionType": "data-transform";
        // ID of the transformation to apply.
        "DataTransformID": number;
    }
}
```

**Javascript example**

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

---

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