From a backend service, retrieve the device twin via the IoT Hub REST API: GET https://<hub>.azure-devices.net/twins/<deviceId>?api-version=2021-04-12 using a service SAS token; the response contains desired, reported, and tags sections
Update desired properties by PATCH to the same URI with a body like {"properties":{"desired":{"reportingInterval":30}}}; include the $version for optimistic concurrency
On the device, subscribe to the MQTT topic $iothub/twin/PATCH/properties/desired/# to receive incremental desired property updates; send GET to $iothub/twin/GET/# on connect to retrieve the full twin
After applying a desired configuration, publish the new reported state to $iothub/twin/PATCH/properties/reported/ with a request ID; IoT Hub returns HTTP 204 on success
To invoke a direct method, POST to https://<hub>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12 with {"methodName":"reboot","responseTimeoutInSeconds":30,"payload":{}}; the device must be online
On the device, subscribe to $iothub/methods/POST/# to receive method invocations; respond by publishing to $iothub/methods/res/<status>/?$rid=<requestId> with a JSON payload within the timeout window
Known gotchas
Device twin desired and reported properties each have a 32 KB size limit; tags have an 8 KB limit — exceeding these causes a 413 error and partial twin documents are not saved
Direct methods require the device to be currently connected; invoking a method on an offline device returns a 404 or timeout immediately — use desired twin properties for configuration that should survive reconnects
The twin $version increments on every update; if a device sends a reported patch referencing a stale version it will be accepted (no conflict detection), so the service must query the twin after patching to confirm convergence
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp