# 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.

::: warning 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](./mqtt_integration.md) 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](../deployment/emqx_fleets_manage_deployment.md#deployment-api-keys).

## Authentication

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

```text
Authorization: Basic <base64(apiKey:apiSecret)>
```

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

## Report Shadow State

Report the device's current state:

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

```bash
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:

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

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

Response:
```json
{
  "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:

```text
POST /api/v1/thing-datas/events
```

```bash
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:

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

```bash
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

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

```bash
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

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

### Report Job Execution Status

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

```bash
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](./mqtt_integration.md)
- [Device Shadow Sync](./device_shadow_sync.md)