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 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 for details, and the Security reference 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:

Name
skip
Type
integer
Description
Number of records to skip before the page starts.
Name
take
Type
integer
Description
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:

{
  "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:

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