API

Hermetry has three ways for your own systems to work with your organisation, and a separate API for devices. This section covers the first three.

Interface	Direction	Who uses it	Login
Management REST API	Your system calls Hermetry	ERPs, MES, ticket systems, scripts, reports	API key
Webhooks	Hermetry calls your system	Anything that must react to events: a device going offline, an alarm opening, a command ending	A signing secret you verify
MCP servers	An AI assistant calls Hermetry	AI assistants that support MCP	API key or a sign-in (OAuth)
Device API	Devices send data and receive commands	Devices and gateways	Device token, MQTT user name and password, or certificate

The device API is documented with the devices: MQTT, Device HTTP API and MQTT topics and payloads. Do not use an API key on a device, and do not use a device token in an integration.

What you can do with the management API

With an API key you can do from code what a member can do in the app, within the permissions you give the key:

• list, create, change and delete devices and device profiles, and rotate device credentials,
• read and write attributes, read the latest values and the history of telemetry,
• send commands to devices and read their results,
• list, acknowledge and resolve alarms, and replace a profile’s alarm rules,
• build and read the tree of sites and assets, and place devices in it,
• register firmware, start rollouts and change device settings,
• manage LoRaWAN gateways and devices.

The REST API has no route for writing telemetry. Readings come from devices (MQTT or HTTP) or from flows.

A first call

1. Open API Keys and create a key with the Read only preset of the devices module. See Authentication.
2. Find your organisation id (tenantId) in the address bar of the app: https://<your host>/tenant/<tenantId>/admin/....
3. Call the device list:

curl -s "https://<your host>/tenant/<tenantId>/api/iot/devices?pageSize=5" \
  -H "Authorization: Bearer sk_live_…"

The answer is { "devices": [...], "total": 42 }.

In this section

Getting started:

• Authentication: API keys, permissions, networks, expiry, rotation.
• REST API basics: paths, lists, paging, sorting, filters and conventions.
• Errors and rate limits: the error body, every status code and the limits that answer 429.

Route references:

• Devices and profiles API
• Telemetry and attributes API
• Commands API
• Alarms API
• Sites and assets API
• Firmware and device settings API
• LoRaWAN API

Events:

• Webhooks: create, sign, retry, test.
• Webhook event reference: every IoT event with an example payload.

AI assistants:

• AI assistants (MCP): what an assistant can do and what it never can.
• Connect an AI assistant
• MCP keys and connected apps
• MCP tools reference
• MCP settings and safety

Before you build an integration

• Give each integration its own key with only the permissions it needs. See API key hardening.
• Expect 429 and honour Retry-After.
• Treat ids as opaque UUIDs. Never build them yourself.
• Prefer webhooks to polling for changes: a device’s connection, an alarm, a command result.
• API keys and webhooks are managed by administrators. Rotating a webhook’s signing secret needs the Owner role.