Reserved topics
Topics that begin with a dollar sign ($) are reserved for use by AWS IoT. You can subscribe and publish to these reserved topics as they allow; however, you can't create new topics that begin with a dollar sign. Unsupported publish or subscribe operations to reserved topics can result in a terminated connection.
Asset model topics
Topic | Client operations allowed | Description |
---|---|---|
$aws/sitewise/asset-models/ |
Subscribe |
AWS IoT SiteWise publishes asset property notifications to this topic. For more information, see Interacting with other AWS services in the AWS IoT SiteWise User Guide. |
Device Defender topics
These messages support response buffers in Concise Binary Object
Representation (CBOR) format and JavaScript Object Notation (JSON), depending on
the payload-format
of the topic.
payload-format |
Response format data type |
---|---|
cbor | Concise Binary Object Representation (CBOR) |
json | JavaScript Object Notation (JSON) |
For more information, see Sending metrics from devices.
Topic | Allowed operations | Description |
---|---|---|
$aws/things/ |
Publish |
Device Defender agents publish metrics to this topic. For more information, see Sending metrics from devices. |
$aws/things/ |
Subscribe |
AWS IoT publishes to this topic after a Device Defender agent publishes a successful
message
to $aws/things/ |
$aws/things/ |
Subscribe |
AWS IoT publishes to this topic after a Device Defender agent publishes an unsuccessful
message
to $aws/things/ |
Event topics
Topic | Client operations allowed | Description |
---|---|---|
$aws/events/certificates/registered/ |
Subscribe |
AWS IoT publishes this message when AWS IoT automatically
registers a certificate and when a client presents a
certificate with the |
$aws/events/presence/connected/ |
Subscribe |
AWS IoT publishes to this topic when an MQTT client with the specified client ID connects to AWS IoT. For more information, see Connect/Disconnect events. |
$aws/events/presence/disconnected/ |
Subscribe |
AWS IoT publishes to this topic when an MQTT client with the specified client ID disconnects to AWS IoT. For more information, see Connect/Disconnect events. |
$aws/events/subscriptions/subscribed/ |
Subscribe |
AWS IoT publishes to this topic when an MQTT client with the specified client ID subscribes to an MQTT topic. For more information, see Subscribe/Unsubscribe events. |
$aws/events/subscriptions/unsubscribed/ |
Subscribe |
AWS IoT publishes to this topic when an MQTT client with the specified client ID unsubscribes to an MQTT topic. For more information, see Subscribe/Unsubscribe events. |
$aws/events/thing/ |
Subscribe |
AWS IoT publishes to this topic when the |
$aws/events/thing/ |
Subscribe |
AWS IoT publishes to this topic when the |
$aws/events/thing/ |
Subscribe |
AWS IoT publishes to this topic when the |
$aws/events/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing group, |
$aws/events/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing group, |
$aws/events/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing group, |
$aws/events/thingType/ |
Subscribe |
AWS IoT publishes to this topic when the |
$aws/events/thingType/ |
Subscribe |
AWS IoT publishes to this topic when the |
$aws/events/thingType/ |
Subscribe |
AWS IoT publishes to this topic when the |
$aws/events/thingTypeAssociation/thing/ |
Subscribe |
AWS IoT publishes to this topic when thing, |
$aws/events/thingGroupMembership/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing, |
$aws/events/thingGroupMembership/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing, |
$aws/events/thingGroupHierarchy/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing group, |
$aws/events/thingGroupHierarchy/thingGroup/ |
Subscribe |
AWS IoT publishes to this topic when thing group, |
Fleet provisioning topics
These messages support response buffers in Concise Binary Object
Representation (CBOR) format and JavaScript Object Notation (JSON), depending on
the payload-format
of the topic.
payload-format |
Response format data type |
---|---|
cbor | Concise Binary Object Representation (CBOR) |
json | JavaScript Object Notation (JSON) |
For more information, see Device provisioning MQTT API.
Topic | Client operations allowed | Description |
---|---|---|
$aws/certificates/create/ |
Publish |
Publish to this topic to create a certificate from a certificate signing request (CSR). |
$aws/certificates/create/ |
Subscribe |
AWS IoT publishes to this topic after a successful call to
$aws/certificates/create/ |
$aws/certificates/create/ |
Subscribe |
AWS IoT publishes to this topic after an unsuccessful call to
$aws/certificates/create/ |
$aws/certificates/create-from-csr/ |
Publish |
Publishes to this topic to create a certificate from a CSR. |
$aws/certificates/create-from-csr/ |
Subscribe |
AWS IoT publishes to this topic a successful call to
$aws/certificates/create-from-csr/ |
$aws/certificates/create-from-csr/ |
Subscribe |
AWS IoT publishes to this topic an unsuccessful call to
$aws/certificates/create-from-csr/ |
$aws/events/presence/connected/ |
Subscribe |
AWS IoT publishes to this topic when an MQTT client with the specified client ID connects to AWS IoT. For more information, see Connect/Disconnect events. |
$aws/provisioning-templates/ |
Publish |
Publish to this topic to register a thing. |
$aws/provisioning-templates/ |
Subscribe |
AWS IoT publishes to this topic after a successful call to
$aws/provisioning-templates/ |
$aws/provisioning-templates/ |
Subscribe |
AWS IoT publishes to this topic after an unsuccessful call to
$aws/provisioning-templates/ |
Job topics
The client operations noted as Receive in this table indicate topics that AWS IoT publishes directly to the client that requested it, whether the client has subscribed to the topic or not. Clients should also expect to receive these response messages even if they have not subscribed to them.
These response messages do not pass through the message broker and they cannot
be subscribed to by other clients or rules. To subscribe to job activity related
messages, use the notify
and notify-next
topics.
For more information, see Jobs device MQTT and HTTPS APIs.
Topic | Client operations allowed | Description |
---|---|---|
$aws/things/ |
Publish |
Devices publish a message to this topic to make a
|
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic to receive successful responses
from a |
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic when a
|
$aws/things/ |
Publish |
Devices publish a message to this topic to make a
|
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic to receive successful responses to
a |
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic when a
|
$aws/things/ |
Publish |
Devices publish a message to this topic to make a
|
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic to receive successful responses to
a |
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic when a
|
$aws/things/ |
Publish |
Devices publish a message to this topic to make an
|
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic to receive successful
responses to an Only the device that publishes to
$aws/things/ |
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic when an
Only the device that publishes to
$aws/things/ |
$aws/things/ |
Subscribe |
Devices subscribe to this topic to receive notifications when a job execution is added or removed to the list of pending executions for a thing. For more information, see Jobs device MQTT and HTTPS APIs. |
$aws/things/ |
Subscribe |
Devices subscribe to this topic to receive notifications when the next pending job execution for the thing is changed. For more information, see Jobs device MQTT and HTTPS APIs. |
$aws/events/job/ |
Subscribe |
The Jobs service publishes an event on this topic when a job completes. For more information, see Jobs events. |
$aws/events/job/ |
Subscribe |
The Jobs service publishes an event on this topic when a job is canceled. For more information, see Jobs events. |
$aws/events/job/ |
Subscribe |
The Jobs service publishes an event on this topic when a job is deleted. For more information, see Jobs events. |
$aws/events/job/ |
Subscribe |
The Jobs service publishes an event on this topic when a job cancellation begins. For more information, see Jobs events. |
$aws/events/job/ |
Subscribe |
The Jobs service publishes an event on this topic when a job deletion begins. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when job execution succeeds. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when a job execution fails. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when a job execution is rejected. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when a job execution is canceled. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when a job execution times out. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when a job execution is removed. For more information, see Jobs events. |
$aws/events/jobExecution/ |
Subscribe |
The Jobs service publishes an event on this topic when a job execution is deleted. For more information, see Jobs events. |
Rule topics
Topic | Client operations allowed | Description |
---|---|---|
$aws/rules/ |
Publish |
A device or an application publishes to this topic to trigger rules directly. For more information, see Reducing messaging costs with basic ingest. |
Secure tunneling topics
Topic | Client operations allowed | Description |
---|---|---|
$aws/things/ |
Subscribe |
AWS IoT publishes this message for an IoT agent to start a local proxy on the remote device. For more information, see IoT agent snippet. |
Shadow topics
The topics in this section are used by named and unnamed shadows. The topics used by each differ only in the topic prefix. This table shows the topic prefix used by each shadow type.
ShadowTopicPrefix value
|
Shadow type |
---|---|
$aws/things/thingName /shadow
|
Unnamed (classic) shadow |
$aws/things/thingName /shadow/name/shadowName |
Named shadow |
To create a complete topic, select the
ShadowTopicPrefix
for the type of shadow to which you
want to refer, replace thingName
and if applicable,
shadowName
, with their corresponding values, and then
append that with the topic stub as shown in the following table. Remember that
topics are case sensitive.
Topic | Client operations allowed | Description |
---|---|---|
|
Publish/Subscribe |
A device or an application publishes to this topic to delete a shadow. For more information, see /delete. |
|
Subscribe |
The Device Shadow service sends messages to this topic when a shadow is deleted. For more information, see /delete/accepted. |
|
Subscribe |
The Device Shadow service sends messages to this topic when a request to delete a shadow is rejected. For more information, see /delete/rejected. |
|
Publish/Subscribe |
An application or a thing publishes an empty message to this topic to get a shadow. For more information, see Device Shadow MQTT topics. |
|
Subscribe |
The Device Shadow service sends messages to this topic when a request for a shadow is made successfully. For more information, see /get/accepted. |
|
Subscribe |
The Device Shadow service sends messages to this topic when a request for a shadow is rejected. For more information, see /get/rejected. |
|
Publish/Subscribe |
A thing or application publishes to this topic to update a shadow. For more information, see /update. |
|
Subscribe |
The Device Shadow service sends messages to this topic when an update is successfully made to a shadow. For more information, see /update/accepted. |
|
Subscribe |
The Device Shadow service sends messages to this topic when an update to a shadow is rejected. For more information, see /update/rejected. |
|
Subscribe |
The Device Shadow service sends messages to this topic when a difference is detected between the reported and desired sections of a shadow. For more information, see /update/delta. |
|
Subscribe |
AWS IoT publishes a state document to this topic whenever an update to the shadow is successfully performed. For more information, see /update/documents. |
Streaming service topics
These messages support response buffers in Concise Binary Object Representation (CBOR)
format and
JavaScript Object Notation (JSON), depending on the payload-format
of the
topic.
payload-format |
Response format data type |
---|---|
cbor | Concise Binary Object Representation (CBOR) |
json | JavaScript Object Notation (JSON) |
Topic | Client operations allowed | Description |
---|---|---|
$aws/things/ |
Subscribe |
The AWS Streaming service publishes to this topic if the "GetStream" request from a device is accepted. The payload contains the stream data. For more information, see Using the AWS IoT Streaming service in devices. |
$aws/things/ |
Publish |
A device publishes to this topic to perform a "GetStream" request. For more information, see Using the AWS IoT Streaming service in devices. |
$aws/things/ |
Subscribe |
The AWS Streaming service publishes to this topic if the "DescribeStream" request from a device is accepted. The payload contains the stream description. For more information, see Using the AWS IoT Streaming service in devices. |
$aws/things/ |
Publish |
A device publishes to this topic to perform a "DescribeStream" request. For more information, see Using the AWS IoT Streaming service in devices. |
$aws/things/ |
Subscribe |
The AWS Streaming service publishes to this topic if a "DescribeStream" or "GetStream" request from a device is rejected. For more information, see Using the AWS IoT Streaming service in devices. |
Reserved topic ARN
All reserved topic ARNs (Amazon Resource Names) have the following form:
arn:aws:iot:
aws-region
:AWS-account-ID
:topic/Topic
For example,
arn:aws:iot:us-west-2:123EXAMPLE456:topic/$aws/things/thingName/jobs/get/accepted
is an ARN for the reserved topic $aws/things/thingName/jobs/get/accepted
.