Device HTTP API

Use HTTPS when a device cannot keep an MQTT connection: battery devices that wake up, send and sleep, or networks that block MQTT. HTTP messages are handled exactly like MQTT messages: the same payload forms, the same key rules, the same rate limits, the same monthly message count. This page lists every endpoint a device can call.

Basics

The token never goes in the URL, except on profiles that turn on Token in the URL (see below). Client certificates are not used on the HTTP API: devices that log in with X.509 use MQTT. Any path that is not listed here answers 404.

Endpoints

Not available over HTTP: reading attributes (GET /api/v1/attributes), waiting for shared-attribute changes, opening the claim window and asking for firmware. These paths answer 404. Devices that need them use MQTT.

Telemetry uses the same payload forms as MQTT. See MQTT topics and payload reference. A body on POST /api/v1/telemetry that is not JSON is stored as one raw key (up to the profile’s raw size, 4 KB by default).

Endpoint details

{
    "ts": 1759572000000,
    "values": {
        "temperature": 21.5,
        "humidity": 40
    }
}

curl -X POST 'https://<your-host>/api/v1/telemetry' \
  -H 'Content-Type: application/json' \
  -d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'

{
    "error": "invalid_payload"
}

{
    "error": "payload_too_large"
}

{
    "error": "rate_limited"
}

{
    "current_fw_title": "boiler-fw",
    "current_fw_version": "26.10.2",
    "lan.ip": "192.168.1.1"
}

curl -X POST 'https://<your-host>/api/v1/attributes' \
  -H 'Content-Type: application/json' \
  -d '{"current_fw_title":"boiler-fw","current_fw_version":"26.10.2","lan.ip":"192.168.1.1"}'

{
    "error": "invalid_payload"
}

{
    "error": "rate_limited"
}

curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000'

{
    "id": 42,
    "method": "sys.ping",
    "params": {
        "host": "8.8.8.8",
        "count": 3
    }
}

{
    "error": "tls_required"
}

{
    "error": "timeout"
}

{
    "error": "poll_in_progress"
}

{
    "ok": true,
    "result": {
        "sent": 3,
        "received": 3,
        "avg_ms": 18.2
    }
}

curl -X POST 'https://<your-host>/api/v1/rpc/{id}' \
  -H 'Content-Type: application/json' \
  -d '{"ok":true,"result":{"sent":3,"received":3,"avg_ms":18.2}}'

{
    "error": "payload_too_large"
}

{
    "method": "app.request",
    "params": {}
}

curl -X POST 'https://<your-host>/api/v1/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"app.request","params":{}}'

{
    "error": "timeout"
}

{
    "deviceName": "boiler-07",
    "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60",
    "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"
}

curl -X POST 'https://<your-host>/api/v1/provision' \
  -H 'Content-Type: application/json' \
  -d '{"deviceName":"boiler-07","provisionDeviceKey":"pk_8f3b2c1e9d4a7b60","provisionDeviceSecret":"ps_1c9e7f2a4b6d8e03"}'

{
    "status": "SUCCESS",
    "credentialsType": "ACCESS_TOKEN",
    "credentialsValue": "aZ3…"
}

{
    "error": "payload_too_large"
}

Examples

Send one reading, stamped by the server:

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

Send buffered readings with their own times (milliseconds since 1970, UTC):

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[{"ts":1759572000000,"values":{"temperature":21.5}},{"ts":1759572060000,"values":{"temperature":21.7}}]'

Wait for a command and answer it:

curl -s "https://<device host>/api/v1/rpc?timeout=30000" -H "Authorization: Bearer <ACCESS_TOKEN>"
# → {"id": 42, "method": "sys.ping", "params": {...}}
curl -X POST "https://<device host>/api/v1/rpc/42" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" \
  -d '{"ok": true, "result": {"sent": 3, "received": 3}}'

Status codes

Online status for HTTP devices

HTTP devices hold no connection, so a profile with Live connection never shows them online. Give HTTP devices a profile with Recent message (online while the last message is younger than the expected interval times the factor) or Last seen only. See Connection status and activity.

Devices that cannot send headers

Some devices cannot set an Authorization header. For them, turn on Token in the URL in the profile’s Transport & auth tab. The devices may then use:

POST /api/v1/{token}/telemetry
POST /api/v1/{token}/attributes

Commands over plain HTTP

A long poll that does not reach Hermetry over TLS receives only the commands the profile lists under Commands allowed without TLS. Every other command waits for a TLS connection or its expiry. If the list is empty, a plain poll answers 403 tls_required.

Related

• Sending commands to devices
• Device credentials
• Data does not arrive