Skip to main content
Table of Contents

v5 API Overview

The concepts shared across every ZENTRA Cloud v5 API endpoint — base URL, authentication, data access control, rate limiting, pagination, units, and errors. Start here.

v5 API Overview

The ZENTRA Cloud v5 API is the latest-generation data interface from METER Group, designed to provide faster, more reliable, and more consistent access to environmental and device data.

This overview covers the concepts that apply across every v5 endpoint — the base URL, authentication, access control, rate limiting, pagination, and error handling. Read it once, then use the per-endpoint reference articles for parameters and response shapes.

New to the API? Start with Getting Started, which walks you from account creation to your first request.

Base URL

All v5 endpoints live under a single host:

https://api.zentracloud.io/v5

Authentication

Every request is authenticated with your personal API key, passed in a request header:

X-API-Key: YOUR_API_KEY

The user is resolved from the key — you never pass a user ID. Each key only ever sees the devices and data it is authorized to access, so the same request made by two different users can return different results. A missing or invalid key returns 401 Unauthorized.

Your key is per-user and should be treated like a password. See API Token for where to find, copy, and regenerate it.

Data access control

Access to device data is controlled by the organization. To read a device's data, your user account must be a member of the organization that the device belongs to, and your role in that organization must be Administrator, Editor, or User. Project-level access counts as membership for device discovery.

Endpoints

The v5 surface is intentionally small. Each endpoint has its own reference article:

Endpoint

Method & path

What it does

List Devices

GET /v5/devices

Coming soon. Discover the devices your key can access and collect their device_id values.

Get Device Readings

ReadingsGET /v5/devices/{device_id}/data

Pull time-series measurements for a single device.

Rate limiting

The v5 API is rate limited per user using the Generic Cell Rate Algorithm (GCRA), which allows short bursts and then a steady sustained rate. Requests beyond your limit return 429 Too Many Requests.

For the burst and steady-state numbers, reset behavior, and retry guidance, see Rate Limiting.

Pagination

Pagination differs by endpoint because the two endpoints return fundamentally different data, so check each endpoint's article for specifics:

  • List Devices uses offset-style pagination with page_num and limit, ordered by device ID ascending. Iterate page_num=1, 2, 3, … up to total_pages.
  • Get Device Readings uses calendar-month windows aligned to UTC. Each page holds a single calendar month of data, and a next_token is returned when more pages are available. In descending order (newest first), the first page contains only the portion of the current month up to your requested end, so it is often smaller than later pages.

Units

Endpoints that return measurements accept a units parameter of metric or imperial. The default is metric.

Errors

The API uses standard HTTP status codes. The ones you'll encounter across endpoints are 401 (auth), 403 (not a member of the requested organization), 422 (invalid parameters), and 429 (rate limit).

See Errors for the full model and how to handle each. Endpoint articles note any endpoint-specific causes.

How did we do?

Getting Started

Contact