---
title: Devices API
description: List, retrieve, create, update and delete Devices in an organization via the ControlCom Connect REST API.
source: https://documentation.controlcomtech.com/api-reference/devices
---

# Devices

A Device represents a piece of hardware or a data source that reports readings to the platform. The Devices API lists, creates, updates and deletes the Devices in an organization.

> **Workflow Stage: Integrate**

## List Devices

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

Returns the organization's Devices, newest first. Archived Devices are excluded. Reading requires valid credentials but no specific permission.

* `search` (string): Case-insensitive filter on the Device name.
* `type` (string): One or more Device types, comma-separated. Types: `CONTROLCOM_GATEWAY`, `CUSTOM_DEVICE`, `LORAWAN_GATEWAY_CLOUD`, `LORAWAN_GATEWAY_EDGE`, `LORAWAN_DEVICE`.
* `parentDeviceId` (string): Return only the children of this Device.
* `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?take=25' \
--header 'Authorization: Basic <Base64 encoded key ID and secret>'
```

**Response**

```json
{
  "count": 42,
  "items": [
    {
      "id": "clxq8...",
      "name": "Main Building Gateway",
      "description": "Edge gateway in the main electrical room",
      "type": "CONTROLCOM_GATEWAY",
      "isActive": true,
      "isOnline": true,
      "locationId": "clxq2...",
      "createdDateTime": "2025-11-03T14:21:09.000Z",
      "updatedDateTime": "2026-01-12T08:02:44.000Z"
    }
  ]
}
```

## Retrieve a Device

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

Returns a single Device by id.

## Create a Device

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

Requires the `CreateDevice` permission. The body is discriminated by `type`; every type accepts the common fields, and the LoRaWAN types add a `configuration` object.

* `type` (string): Required. One of `CONTROLCOM_GATEWAY`, `CUSTOM_DEVICE`, `LORAWAN_GATEWAY_CLOUD`, `LORAWAN_GATEWAY_EDGE`, `LORAWAN_DEVICE`.
* `name` (string): Required, 5 to 100 characters.
* `description` (string): Optional, up to 500 characters.
* `locationId` (string | null): Optional. The Location where the device is installed.
* `configuration` (object): LoRaWAN types only. Gateways take `gatewayEui` (16 hex characters) and `rfRegion`; a US915 region also requires `subBand` (1 to 8). LoRaWAN devices take `devEui`, `appEui` (16 hex characters each) and `appKey` (32 hex characters).

**cURL**

```bash
curl -X POST 'https://api.controlcomtech.com/primary/v1/<organizationId>/devices' \
--header 'Authorization: Basic <Base64 encoded key ID and secret>' \
--header 'Content-Type: application/json' \
--data '{
  "type": "CUSTOM_DEVICE",
  "name": "Chiller Plant Meter",
  "description": "Power meter on the chiller plant feed"
}'
```

## Update a Device

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

Requires the `UpdateDevice` permission. `type` must always be included, since it selects the validation rules; `name`, `description` and `locationId` are the updatable fields.

## Delete a Device

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

Requires the `DeleteDevice` permission. Returns `204 No Content` on success. Deleting a Device also removes its Variables and everything that depends on them, so treat this as destructive.