Device HTTP API

Use HTTPS, když zařízení nemůže udržet připojení MQTT: bateriová zařízení, která se probudí, odešlou data a znovu usnou, nebo sítě, které MQTT blokují. Zprávy HTTP se zpracovávají stejně jako zprávy MQTT: stejné tvary datových zpráv, stejná pravidla klíčů, stejné limity počtu požadavků a stejný měsíční počet zpráv. Tato stránka uvádí každý koncový bod, který zařízení může volat.

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