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.

Name
search
Type
string
Description
Case-insensitive filter on the Variable name.
Name
deviceIds[]
Type
string[]
Description
Limit to Variables on these Devices.
Name
assetIds[]
Type
string[]
Description
Limit to Variables assigned to these Assets.
Name
folderIds[]
Type
string[]
Description
Limit to Variables in these variable folders.
Name
skip
Type
integer
Description
Records to skip. See Pagination.
Name
take
Type
integer
Description
Records to return per page.

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

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.

Name
topicPropertyPath
Type
string
Description
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.
Name
type
Type
string
Description
Required. STRING, NUMBER or BOOLEAN.
Name
name
Type
string
Description
Required, 2 to 100 characters.
Name
isLoggingEnabled
Type
boolean
Description
Required. Whether readings are stored as time-series history.
Name
description
Type
string | null
Description
Optional, up to 500 characters.
Name
unit
Type
string
Description
Optional, 1 to 9 characters, shown next to values.
Name
classificationType
Type
string
Description
Optional electrical classification, such as ELECTRICAL_GENERATOR_KW or ELECTRICAL_ATS_NORMAL_POSITION, used by Asset features.
Name
folderId
Type
string | null
Description
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.