---
title: API Reference
description: Introduction to the ControlCom Connect REST API: base URLs, authentication, pagination, and conventions for integrating with the platform.
source: https://documentation.controlcomtech.com/api-reference
---

# API Reference

The ControlCom Connect REST API lets you manage Devices, Variables, Assets and Alarms programmatically, read Dashboards, and connect the platform to third-party systems.

> **Workflow Stage: Integrate**

## Base URLs

The platform exposes two APIs, both on the same host:

```
https://api.controlcomtech.com/primary/v1
```

The management API documented in this reference. Every resource path starts with your organization id, for example `/primary/v1/<organizationId>/devices`.

```
https://api.controlcomtech.com/data/v1
```

The data ingestion API, used to push readings into the platform over HTTP. See [Sending data over HTTP](https://documentation.controlcomtech.com/build/sending-data/http) in the Build track.

All requests must be made over HTTPS. The API is intended for server-side use; browsers on other origins are blocked by the API's CORS policy.

## Authentication

The API authenticates with API key credentials (HTTP Basic) or a signed-in user's JSON Web Token (Bearer). API keys are created under **Settings → API keys** and carry the permissions of the role they are assigned. See [Authentication](https://documentation.controlcomtech.com/api-reference/authentication) for details, and the [Security reference](https://documentation.controlcomtech.com/references/security) for transport and best-practice guidance.

## Conventions

The API follows predictable REST conventions:

* Resources are scoped to an organization: `/primary/v1/<organizationId>/<resource>`.
* Request and response bodies are JSON.
* Standard HTTP status codes indicate success or failure.
* Creates use `POST`, partial updates use `PATCH`, and deletes use `DELETE`. Several resources archive on delete rather than destroying data, and offer a restore endpoint.

Some list filters accept multiple values. Depending on the endpoint, these are passed either comma-separated in one parameter (`?type=CUSTOM_DEVICE,LORAWAN_DEVICE`) or as a repeated bracket parameter (`?locationIds[]=abc&locationIds[]=def`). Each endpoint page states which form it uses.

## Pagination

List endpoints paginate with offset parameters and return the total count alongside the page:

* `skip` (integer): Number of records to skip before the page starts.
* `take` (integer): Number of records to return. When omitted, the endpoint returns the entire result set, so always pass an explicit `take` on collections that can grow.

Responses have the shape:

```json
{
  "count": 132,
  "items": [ ... ]
}
```

`count` is the total number of matching records, not the page size, so `skip + take < count` tells you another page exists.

## Errors

The API reports failures with standard status codes and a JSON body.

| Status | Meaning                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------ |
| `400`  | Validation failed. The body contains an `errors` array describing each invalid field.                  |
| `401`  | Missing or invalid credentials.                                                                        |
| `403`  | The credentials are valid but lack a required permission. The body lists them in `missingPermissions`. |
| `404`  | The record does not exist in this organization.                                                        |
| `409`  | A uniqueness conflict, such as reusing a name that must be unique.                                     |

A permission error looks like:

```json
{
  "missingPermissions": ["CreateDevice"],
  "message": "Request failed to complete. Missing required permissions"
}
```

Browse the **Endpoints** section in the sidebar for individual resource documentation.