---
title: Variables API
description: List, create, update and delete Device Variables via the ControlCom Connect REST API.
source: https://documentation.controlcomtech.com/api-reference/variables
---

# Variables

A Variable is a single data point on a Device, such as a temperature, a breaker state or a running-hours counter. Variables belong to a Device, so their endpoints live under the Devices resource.

> **Workflow Stage: Integrate**

## List Variables

```
GET https://api.controlcomtech.com/primary/v1/<organizationId>/devices/variables
```

Returns Variables across the whole organization. Multi-value filters on this endpoint repeat the parameter with brackets: `?deviceIds[]=a&deviceIds[]=b`.

* `search` (string): Case-insensitive filter on the Variable name.
* `deviceIds[]` (string\[]): Limit to Variables on these Devices.
* `assetIds[]` (string\[]): Limit to Variables assigned to these Assets.
* `folderIds[]` (string\[]): Limit to Variables in these variable folders.
* `skip` (integer): Records to skip. See [Pagination](https://documentation.controlcomtech.com/api-reference#pagination).
* `take` (integer): Records to return per page.

**cURL**

```bash
curl 'https://api.controlcomtech.com/primary/v1/<organizationId>/devices/variables?take=25' \
--header 'Authorization: Basic <Base64 encoded key ID and secret>'
```

**Response**

```json
{
  "count": 214,
  "items": [
    {
      "id": "clxv1...",
      "name": "Generator 1 kW",
      "topicPropertyPath": "generators/gen1/kw",
      "type": "NUMBER",
      "unit": "kW",
      "isLoggingEnabled": true,
      "deviceId": "clxq8..."
    }
  ]
}
```

## List a Device's Variables

```
GET https://api.controlcomtech.com/primary/v1/<organizationId>/devices/<deviceId>/variables
```

Returns one Device's Variables, with the same `search`, `skip` and `take` parameters. `search` also matches the topic property path and description.

## Retrieve a Variable

```
GET https://api.controlcomtech.com/primary/v1/<organizationId>/devices/variables/<variableId>
```

Returns a single Variable by id.

## Create a Variable

```
POST https://api.controlcomtech.com/primary/v1/<organizationId>/devices/<deviceId>/variables
```

Requires the `CreateVariable` permission.

* `topicPropertyPath` (string): Required, 5 to 500 characters, no whitespace. The key under which the Device reports this value; incoming readings are matched to the Variable by this path.
* `type` (string): Required. `STRING`, `NUMBER` or `BOOLEAN`.
* `name` (string): Required, 2 to 100 characters.
* `isLoggingEnabled` (boolean): Required. Whether readings are stored as time-series history.
* `description` (string | null): Optional, up to 500 characters.
* `unit` (string): Optional, 1 to 9 characters, shown next to values.
* `classificationType` (string): Optional electrical classification, such as `ELECTRICAL_GENERATOR_KW` or `ELECTRICAL_ATS_NORMAL_POSITION`, used by Asset features.
* `folderId` (string | null): Optional variable folder to file the Variable under.

## Update a Variable

```
PATCH https://api.controlcomtech.com/primary/v1/<organizationId>/devices/variables/<variableId>
```

Requires the `UpdateVariable` permission. Updatable fields: `name`, `description`, `unit`, `isLoggingEnabled`, `classificationType` and `folderId`. The `topicPropertyPath` and `type` are fixed at creation.

## Delete a Variable

```
DELETE https://api.controlcomtech.com/primary/v1/<organizationId>/devices/<deviceId>/variables/<variableId>
```

Requires the `DeleteVariable` permission. Deleting a Variable removes its stored history.