canonical: https://jentic.com/apis/amazonaws.com/aws-iot-data

# AWS IoT Data Plane

Jentic publishes the only available OpenAPI specification for AWS IoT Data Plane, keeping it validated and agent-ready. The IoT Data Plane API is the runtime surface for publishing MQTT messages, reading and updating device shadows, and managing retained messages on AWS IoT Core. It is a focused 7-endpoint API used by applications and backend services that interact with the live state of connected devices rather than configuring the IoT Core platform itself.

## For AI agents

Publish MQTT messages, read and update device shadow documents, and manage retained messages on AWS IoT Core to drive the runtime behaviour of connected devices.

## Scope

Does not handle thing registration, certificate management, or rule engine configuration - use for runtime MQTT publish, device shadows, and retained messages only.

## Capabilities

- Publish MQTT messages to a topic via HTTPS POST without holding an MQTT connection
- Get and update the unnamed shadow document of a thing
- Get and update named shadows for things that maintain multiple state documents
- Delete a shadow when the device or feature is decommissioned
- List named shadows attached to a specific thing
- Retrieve and list retained messages currently stored on the broker

## Use cases

### Backend-to-Device Command Dispatch

Send commands from a backend service to connected devices without maintaining an MQTT client. The Publish operation pushes a JSON payload to a topic over HTTPS using SigV4, and the device receives it via its existing MQTT subscription. This is the simplest pattern for occasional commands such as firmware update triggers or configuration nudges.

Example prompt: Call POST /topics/devices/fan-01/cmd with payload {"action":"setSpeed","value":75} and qos=1

### Shadow-Based State Synchronisation

Use device shadows as the system of record for a thing's desired and reported state. Backends call UpdateThingShadow to set desired state, devices call UpdateThingShadow when their reported state changes, and either side can call GetThingShadow to read the current document. The API supports both unnamed and named shadows for things that need multiple feature-scoped state objects.

Example prompt: Call GET /things/warehouse-fan-01/shadow to read the current document, then PUT to the same path with payload {"state":{"desired":{"fanSpeed":50}}}

### Retained Message Bootstrap

Use retained messages to give newly-connecting clients an immediate state snapshot. The broker stores the last retained message per topic; ListRetainedMessages and GetRetainedMessage let backend tools enumerate and inspect what is currently retained. This is useful for diagnosing why a fleet of devices is starting up with stale state.

Example prompt: Call GET /retainedMessage to list retained messages, then GET /retainedMessage/{topic} for any topic that needs inspection

### AI Agent Device Operations

Through Jentic, an AI agent can act as a device operator - publishing commands, inspecting shadows, and updating desired state in response to natural-language instructions. The 7 IoT Data Plane operations are surfaced as discoverable Jentic tools so the agent picks the right one from intent.

Example prompt: Search Jentic for 'update aws iot device shadow', load the UpdateThingShadow schema, and execute with thingName and a state payload

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /topics/{topic} | Publish - publish a message to a topic over HTTPS |
| GET | /things/{thingName}/shadow | GetThingShadow - read a thing's unnamed or named shadow |
| POST | /things/{thingName}/shadow | UpdateThingShadow - update a thing's shadow document |
| DELETE | /things/{thingName}/shadow | DeleteThingShadow - delete a shadow |
| GET | /api/things/shadow/ListNamedShadowsForThing/{thingName} | ListNamedShadowsForThing - list named shadows on a thing |
| GET | /retainedMessage/{topic} | GetRetainedMessage - fetch a retained message for a topic |
| GET | /retainedMessage | ListRetainedMessages - list retained messages on the account |

## Key resources

- **Topic** — MQTT topic that receives published messages
- **Shadow** — Persistent document representing a thing's reported and desired state
- **NamedShadow** — Named state document attached to a thing for feature-specific state
- **RetainedMessage** — Last-retained message per topic served to new subscribers

## Why Jentic

- **Setup:** Wiring the AWS IoT Data Plane by hand means implementing AWS Signature v4 request signing, resolving your account's data-ats.iot endpoint, and mapping publish, shadow, and retained-message calls to their REST paths yourself. Through Jentic you install once, import AWS IoT Data Plane from the API Directory, store the AWS credentials once, and your agent calls it.
- **Permission scoping:** This API puts the thing name and topic in the URL path (/things/{thingName}/shadow and /topics/{topic}), so a rule can pin your agent to one thing's shadow or one topic. You choose the operations it may call, so destructive ones like DeleteThingShadow are not included unless you add them.
- **Credential handling:** Your AWS credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'publish a message to an AWS IoT topic' or 'update a device shadow', and Jentic returns the matching AWS IoT Data Plane operation with its input schema so the agent calls the right endpoint without browsing the AWS service reference.

## Related APIs

- **AWS IoT Jobs Data Plane** — Devices fetch and update job executions over the same kind of runtime endpoint
- **AWS Greengrass** — Edge runtime that bridges devices to AWS IoT Core and the Data Plane API
- **AWS IoT Events** — State machines that consume telemetry published via the IoT Data Plane

## FAQ

### Why is there no official OpenAPI spec for AWS IoT Data Plane?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AWS IoT Data Plane via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AWS IoT Data Plane API use?

The API uses AWS Signature Version 4 (HMAC) request signing with an AWS access key ID and secret access key. The same endpoint also accepts client certificate authentication for devices, but the OpenAPI spec covers the SigV4 path used by backend applications.

### Can I update a device shadow with the IoT Data Plane API?

Yes. Call POST /things/{thingName}/shadow with a JSON body containing a state object such as {"state":{"desired":{"fanSpeed":75}}}. For named shadows, append the ?name=shadow-name query parameter to target a specific named shadow.

### What are the rate limits for the AWS IoT Data Plane API?

AWS applies per-account, per-region request quotas to IoT Data Plane operations and these vary by call. Publish has higher throughput than shadow updates. Check AWS Service Quotas for current limits and request increases if needed.

### How do I publish a command to a topic through Jentic?

Search Jentic for 'publish to aws iot topic', load the Publish schema, and execute with the topic in the path and a payload body. Jentic signs the request with SigV4 so the agent does not handle AWS credentials directly.

### What is the difference between this API and AWS IoT Core control plane?

This data-plane API operates on runtime state - publishing messages, reading and writing shadows, and managing retained messages. The IoT Core control plane manages things, certificates, policies, and rules. Use this API at runtime; use the control plane for configuration.

### Can I limit what my agent is allowed to do with the AWS IoT Data Plane API?

Yes. Because you run Jentic One yourself, your own rules decide which of the 7 IoT Data Plane operations your agent may call, so you can grant Publish and GetThingShadow while leaving out destructive ones like DeleteThingShadow. The thing name and topic live in the URL path (/things/{thingName}/shadow and /topics/{topic}), so a rule can pin the agent to a single thing's shadow or one topic rather than the whole account. Your AWS credentials are stored and injected by your own instance at execution time, so the agent never sees the access key or secret it signs requests with.