Skip to main content

Discovering sensors

The readings endpoint and the metadata endpoint both key on a sensor UUID. If you only know your gateway's device key (for example capteur-1 for a Webdyn channel), call the discovery endpoint first to find the matching UUID.

List the sensors on a site​

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.powernaut.io/v1/connect/sites/$SITE_ID/sensors"

Response:

[
  {
    "id": "c57e75b1-9860-4ea5-a7cf-9d04704974a4",
    "external_id": "capteur-1",
    "connection_point_id": "6d570914-485b-4cd8-8c93-ada58293e20b",
    "measurements": [{ "key": "irradiance", "unit": "W/m2" }]
  }
]

The fields match the metadata endpoint exactly, so anything you can do with GET /v1/connect/sensors/{id} you can do with each entry from this list.

End-to-end: device key to readings​

Use the device key (external_id) to pick the sensor you want, then pass its UUID to the readings endpoint.

import os
import requests
import pandas as pd

base = "https://api.powernaut.io/v1/connect"
headers = {"Authorization": f"Bearer {os.environ['TOKEN']}"}
site_id = os.environ["SITE_ID"]

sensors = requests.get(
    f"{base}/sites/{site_id}/sensors",
    headers=headers,
    timeout=30,
).json()

sensor = next((s for s in sensors if s["external_id"] == "capteur-1"), None)
if sensor is None:
    raise RuntimeError("No sensor with external_id capteur-1 on this site")

readings = requests.get(
    f"{base}/sensors/{sensor['id']}/readings",
    headers=headers,
    params={"start": "2026-04-01T00:00:00Z", "end": "2026-04-02T00:00:00Z"},
    timeout=60,
).json()

df = pd.DataFrame(readings["data"])
df["timestamp"] = pd.to_datetime(df["timestamp"], utc=True)
df = df.set_index("timestamp")
print(df.head())

Error handling​

StatusErrorWhen
403ForbiddenYour API credentials lack the sensor-read scope.
404Not FoundThe site_id does not exist or is not visible to your partner.

Best practices​

Cache the device-key mapping​

Once you have translated capteur-1 to its UUID, cache the pair locally. Sensor IDs are stable, so you only need to call this endpoint when a new device is added or when the cache is cold.

Prefer the listing endpoint over hard-coded UUIDs​

If you are integrating multiple sites, build a small bootstrap step that calls this endpoint per site at start-up. Hard-coded UUIDs in client code drift the moment a sensor is replaced or a site is re-cabled.

Last updated on