Control device HTTPS flow

HTTPS is a supported direct request/response transport for firmware that polls Realer for catalog state and posts command acknowledgements or sensor readings through direct iot/v1 requests.

OAuth token issue and renewal happen over HTTPS. This page describes the HTTPS runtime loop after the device has authenticated.

On this page

Transport and security

The public device API is served from https://api.therealer.com/iot/v1/.... Plain HTTP is not accepted for public device traffic.

Implementation references

This page summarizes the HTTPS runtime sequence. The linked reference pages document request headers, parameters, examples, and response shapes.

Typical HTTPS firmware can omit the OAuth scope parameter; Realer then issues the default HTTPS scopes for catalog reads and feed-data writes. Use the authentication page when you need the full scope reference.

Step Endpoint or reference Firmware purpose
Authenticate OAuth device authentication Issue or renew the Bearer access token.
Read catalog Device catalog Read command desired state and sensor definitions.
Report state Feed-data ingestion Send command acknowledgements, local physical command changes, and sensor values.
Handle responses Response codes Use stable application-level code values for firmware behavior regardless of HTTP status grouping.
Handle field behavior Field semantics Use the shared rules for message_id, desired_id, report_status, expiry, and application results.

Flow diagram

Open full-size SVG
HTTPS API Device Hardware ready Network online Bearer token Device-bound access alt [Token issued] [Rejected] loop [Authenticate until success] Read sensors check actuators alt [Created] [Replay] [Item rejected] opt [Batch upload] loop [HTTPS work loop] POST /oauth/token client credentials Validate client issue Bearer token 200 OK access_token, renew_after 400/401/429 OAuth error GET /iot/v1/devices/{device_id}/commands Check token plan and cadence 200 code 2000 commands[] GET /iot/v1/devices/{device_id}/sensors Check token plan and cadence 200 code 2000 sensors[] POST /iot/v1/devices/{device_id}/feed-data source, value, time, message_id Validate JSON ingest or replay 201 created code 2000 200 idempotent code 2000 4xx/5xx error code + error.type POST /.../feed-data/batches items[] Validate envelope process in order 200 processed per-item results

Firmware loop

  1. Get an OAuth access token
    Call POST /oauth/token with grant_type=client_credentials. For a normal HTTPS-only device, omit scope or request iot:catalog:read iot:feed-data:write.
  2. Read the device catalog
    Call GET /iot/v1/devices/{device_id}/commands and GET /iot/v1/devices/{device_id}/sensors with Authorization: Bearer <access_token>.
  3. Execute commands and collect sensor readings
    Treat command catalog values as desired state from Realer. Keep local safe behavior when authorization, network, or validation fails.
  4. Send feed data
    Call POST /iot/v1/devices/{device_id}/feed-data or POST /iot/v1/devices/{device_id}/feed-data/batches with command acknowledgements and sensor readings.
  5. Renew before expiry
    Use OAuth renew_after to request a new access token before expiry. If renewal fails, authenticate again before protected iot/v1 requests continue.

Request and response example

Feed-data requests use JSON over HTTPS and return application-level results in the response body.

cURL 
curl "https://api.therealer.com/iot/v1/devices/12345/feed-data" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer b11db7f6c816568eb3b156df3aeaa5' \
  -d '{"sensor_id":7,"value":"21.4","value_received_at":"2026-04-24T10:15:00Z","message_id":"sensor-7-20260424T101500Z"}'
POST /iot/v1/devices/{device_id}/feed-data

Send one command acknowledgement or one sensor reading over HTTPS.

Request headers
Authorization
(required)

The Bearer access token obtained from the OAuth token endpoint.

Type: String

Example: Bearer b11db7f6c816568eb3b156df3aeaa5

Content-Type
(required)

The request body media type.

Value: application/json

Path parameters
device_id
(required)

ID (id) of the authenticated control device that is sending feed data.

Type: Integer

Example: 12345

Request body
JSON 
{
  "sensor_id": 7,
  "value": "21.4",
  "value_received_at": "2026-04-24T10:15:00Z",
  "message_id": "sensor-7-20260424T101500Z"
}

Schema: http-feed-data-item.schema.json

Fields
command_id

Exactly one of command_id or sensor_id is required.

sensor_id

Use for sensor readings instead of command_id.

value

Raw source value to validate through the canonical semantic contract.

value_received_at

Canonical source event time for the submitted value.

message_id

Transport-level idempotency key scoped to the authenticated device and semantic source.

desired_id

Optional Realer desired-state id when this command report answers a command sent by Realer.

report_status

Optional command outcome for reports with desired_id: applied, rejected, or stale. For local physical command reports, omit this field; if sent without desired_id, only reported is valid.

Responses

201 Created

JSON 
{
  "code": 2000,
  "status": "created",
  "feed_data_id": 123,
  "message_id": "sensor-7-20260424T101500Z",
  "warnings": []
}

Schema: http-feed-data-result.schema.json

422 Unprocessable Content

Validation failure

JSON 
{
  "code": 4022,
  "error": {
    "type": "validation_failed",
    "message": "feed data ingestion failed",
    "details": {
      "sensor_id": ["is invalid for this device"]
    }
  },
  "request_id": "..."
}

Schema: http-error-response.schema.json

Do not treat HTTP success alone as the application result. Check the JSON code field and, when present, error.type for stable device behavior.

Runtime error handling

HTTP or application result Firmware handling
2xx HTTP with code 2000 Accept the application result and continue the local loop.
2xx HTTP with feed-data status idempotent Treat the replay as success for the same message_id.
4xx HTTP with stable numeric code Use the response-code contract for local behavior. Do not retry blindly unless the documented error is retryable for the device.
401 or expired token Request a new OAuth token, then retry only the current safe operation with the same idempotency key when applicable.
5xx, timeout, or network failure Keep or enter local safe behavior, then retry with backoff and stable message_id values for the same physical event.

Command and sensor handling

Command catalog values represent desired state from Realer. Sensor catalog entries describe values the device can report.

  • For a desired command that is applied locally, send command feed data with the observed physical value.
  • For a desired command that cannot be applied or is stale, send command feed data with report_status set to rejected or stale.
  • For a local physical switch, button, or actuator change, send command feed data without desired_id.
  • For sensor readings, send sensor feed data with the current value, the measurement time, and a unique message_id.
  • After reconnecting, send the latest physical command state and latest relevant sensor state so Realer can reconcile the UI.

When to use MQTT instead

Use the MQTT flow when firmware keeps a broker connection open, needs command desired-state messages without polling, publishes feed data with MQTT over TLS, or needs asynchronous application acknowledgements on a subscribed topic.