API Overview

What the Ardexa API offers, the vocabulary it uses, and where to start.

The Ardexa API gives programmatic access to an Ardexa workgroup: the devices reporting into it, the tables of readings they produce, and the schedules and setpoints that drive them. It is the same API the Ardexa Cloud web app uses.

There are two transports — a RESTful HTTP interface and a websocket interface — and one credential that works on both. To make your first request, start with the API Quick Start Guide. To understand how the pieces fit together first, read on.

Getting access

You need either an API token issued by a workgroup owner, or an Ardexa device that has been granted permission to interact with the API.

A token is scoped to one workgroup, and Ardexa runs clouds in more than one region — a token issued in one region does not authorise requests in another. Tokens are JSON Web Tokens, presented as bearer tokens in the Authorization header, and they expire.

Access and tokens covers how to obtain a token, how it is presented, and how it is renewed, blocked or revoked.

Vocabulary

These terms appear throughout both references and are assumed rather than defined there.

Term	Meaning
Workgroup	The tenant that owns devices, data and users. It appears in nearly every request as the workgroupId path parameter, which some endpoints still label orgName. Find its ID under Admin → Workgroup.
Device	The Ardexa machine reporting into a workgroup — not the equipment it reads from, which is a source. Records identify a device by its ID, not its name; the device list maps one to the other.
Source	The equipment or data origin a device reads from — an inverter, a meter, a log file, a register block. One device usually reports several sources into the same table.
Table	A named collection of records of the same shape, for example a table of inverter readings. Tables are per-workgroup and are what searches and streams operate on.
Scenario	One device, table and source together, with the field definitions for that combination. Live feeds and metadata calls are addressed by scenario.
Device group	A named subset of a workgroup's devices. A token can be restricted to one, in which case everything it reads is narrowed to that group's devices — silently, with no error.

Timestamps

A record carries more than one time, and choosing the wrong one is the most common source of surprising query results.

• event_time is when an event was captured by the Ardexa agent. It is the field records are sorted and filtered on by default

• store_time is when the Ardexa Cloud stored an event. event_time and store_time can differ significantly if an event is captured by an offline Ardexa agent and back-filled to the Cloud at a later time

• Custom date fields, such as Datetime can be present when the plugin supplies a custom timestamp

Searches take a dateField parameter to choose which of these a timeframe applies to. See Timeframe for the accepted formats.

Choosing a transport

Both transports read the same data. The difference is when you get it and whether it can be resumed.

You want	Use	Notes
Records already stored, one request at a time	REST search	Simplest. See API Reference.
To follow a table's stored records as they arrive, and resume after a disconnection	stream:latest over a websocket	Replays from a position or a point in time, within a limited window. See Websocket Reference.
The same, but on a timer rather than a held-open connection	the polled stream endpoint	Returns a batch per request. Reaches back over the same limited window.
The lowest latency, for a live gauge or chart	device:feed / device:bulkFeed	Readings straight off the telemetry queue, before storage. Nothing is replayed and nothing is kept. Use one bulk feed for a dashboard, not one feed per tile.
A result set too large to wait for in one HTTP response	search over a websocket	The cloud pages through it for you.

A connection is bound to the one workgroup named when it is opened, so integrations spanning several workgroups need a connection each.

For how to combine these into a working integration, see Consuming bulk data.

Pagination

The two transports page differently, because they are solving different problems.

• REST search returns a page of up to 10,000 records and, when scrolling is requested, a scroll ID to fetch the next page with. This is the model to use when you are reading a bounded, historical result set. See Search scrolling.

• Websocket streaming is positional rather than paged: each record carries an offset, and a subscription resumes from an offset or a timestamp. This is the model to use when you are following a table rather than reading a fixed set, and it is what lets a subscriber recover after a disconnection.

The parameters themselves are in the two references; do not rely on the shapes being interchangeable.

Rate limits and fair use

Rate limits are applied selectively rather than across the API. These are currently applied to resource-intensive and security-sensitive endpoints. More may be introduced over time, so build your client to tolerate being throttled or refused, backing off and retrying rather than failing. A client that already handles a refusal will not need changing when limits widen.

Ardexa's Cloud support team watches request volume and resource consumption, and may block a token that is consuming an unreasonable share. The most common cause of this is use of an inefficient query pattern to ingest data. See Consuming bulk data for guidance on efficiently interacting with the API for this use case.

If you are planning an integration and are unsure whether its volume is reasonable, ask your Ardexa Account Manager before you build it.

What the reference covers

The published API reference is a curated public surface, not the whole API. It documents a subset of the endpoints offered by the Ardexa Cloud. The remainder are internal, administrative, or under active development.

If you need something that is not documented, ask your Ardexa Account Manager rather than calling an undocumented endpoint — undocumented endpoints carry no compatibility promise.

Versioning

Every documented endpoint lives under the /api/v1 base path. Additive changes — new endpoints, new optional parameters, new fields in a response — are made within v1 and should not break a client that ignores fields it does not recognise.

Where to go next

Start here

• API Quick Start Guide — your first authenticated request, end to end.

• Python examples — worked examples of common use cases.

Access and tokens

• Access and tokens — obtaining, presenting and managing an API token.

• Examining API tokens — what is inside a token.

• Automated API Token Renewal — self-renewing tokens.

• CSRF Tokens — required only for browser session logins.

Task guides

• Consuming bulk data — patterns for an integration that consumes everything a workgroup collects.

• Devices — inspecting devices and their metadata.

• Search — querying tables, including API Search Functions and Search scrolling.

• Stream — following data as it arrives.

• Energy — retrieving energy report data.

• Schedules — driving device setpoints on a schedule.

Reference

• API Reference — generated from the OpenAPI specification.

• Websocket Reference — generated from the AsyncAPI specification.