HTTPS Integration

This page describes how to integrate a device with EMQX Fleets using HTTPS only (the ThingDatas API). Use this path for devices that only need to upload data and can poll for desired state, without maintaining a persistent MQTT connection.

Limitation

HTTPS-only devices cannot receive real-time commands or job notifications. Inbound messages from Fleets (shadow desired state, commands, job dispatch) are delivered via MQTT. If your device needs to receive these, use MQTT Integration instead or in combination.

Prerequisites

• The device is registered as a Thing in your Fleets deployment.
• A Deployment API Key with permission to access /api/v1/thing-datas. See Manage API Keys.

Authentication

All ThingDatas API requests require Basic Auth using a Deployment API Key:

Authorization: Basic <base64(apiKey:apiSecret)>

Example:

AUTH="Basic $(printf '%s:%s' 'ak_yourApiKey' 'your-api-secret' | base64)"

Report Shadow State

Report the device's current state:

POST /api/v1/thing-datas/shadow/reported

curl -X POST https://{fleets-host}/api/v1/thing-datas/shadow/reported \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "state": {
      "reported": {
        "temperature": 21.5,
        "humidity": 58
      }
    },
    "clientToken": "tok-001",
    "version": 0
  }'

• clientToken: Optional. Echoed back in the response for correlation.
• version: Optional. Shadow version for optimistic locking. Set to 0 to auto-increment.

The reported state is stored in GreptimeDB (history) and PostgreSQL (latest). Fleets recomputes the shadow delta after each report.

Read the Current Shadow

Fetch the device's current shadow on startup or to check for pending desired state:

GET /api/v1/thing-datas/{thingName}/shadow

curl https://{fleets-host}/api/v1/thing-datas/thermostat-001/shadow \
  -H "Authorization: $AUTH"

Response:

{
  "reported": { "temperature": 21.5 },
  "desired": { "targetTemperature": 24 },
  "delta": { "targetTemperature": 24 },
  "version": 5,
  "updatedAt": "2026-05-27T10:05:00Z"
}

If delta is non-empty, apply the desired values and report the updated state.

Publish Events

Report a device event:

POST /api/v1/thing-datas/events

curl -X POST https://{fleets-host}/api/v1/thing-datas/events \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "eventType": "highTemperature",
    "severity": "warn",
    "timestamp": 1748390400000,
    "data": { "currentTemp": 45.2 }
  }'

• timestamp: Unix milliseconds. Required.
• severity: info, warn, or error. Optional.
• appId: Optional. Application identifier for multi-app deployments.

Submit a Command Response

If a command was received over MQTT, submit the response over HTTPS:

POST /api/v1/thing-datas/command/response

curl -X POST https://{fleets-host}/api/v1/thing-datas/command/response \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "executionId": "8d88790c-9171-4526-8637-e6d6168bce22",
    "status": "SUCCEEDED",
    "result": { "currentTemperature": 24 },
    "timestamp": 1748390405
  }'

Jobs via HTTPS

Devices can participate in the jobs protocol over HTTPS by polling and reporting status synchronously.

Request Pending Jobs

POST /api/v1/thing-datas/jobs/get

curl -X POST https://{fleets-host}/api/v1/thing-datas/jobs/get \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{"thingName": "thermostat-001", "clientToken": "req-1"}'

Start the Next Pending Job

POST /api/v1/thing-datas/jobs/start-next

Report Job Execution Status

POST /api/v1/thing-datas/jobs/{jobId}/update

curl -X POST https://{fleets-host}/api/v1/thing-datas/jobs/{jobId}/update \
  -H "Content-Type: application/json" \
  -H "Authorization: $AUTH" \
  -d '{
    "thingName": "thermostat-001",
    "status": "SUCCEEDED",
    "statusDetails": { "installedVersion": "2.0.0" },
    "expectedVersion": 1,
    "clientToken": "req-3"
  }'

ThingDatas API Reference

Endpoint	Method	Purpose
/api/v1/thing-datas/shadow/reported	POST	Report shadow state
/api/v1/thing-datas/{thingName}/shadow	GET	Read current shadow
/api/v1/thing-datas/events	POST	Publish an event
/api/v1/thing-datas/command/response	POST	Submit a command response
/api/v1/thing-datas/jobs/get	POST	Request pending jobs
/api/v1/thing-datas/jobs/start-next	POST	Start next pending job
/api/v1/thing-datas/jobs/{jobId}/get	POST	Get a specific job execution
/api/v1/thing-datas/jobs/{jobId}/update	POST	Report job execution status

Next Steps

• MQTT Integration
• Device Shadow Sync