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. |
AWS IoT 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. AWS IoT Device Defender topics only
support MQTT publish.
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 |
AWS IoT 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 AWS IoT Device Defender agent publishes a
successful message to
$aws/things/ |
|
$aws/things/ |
Subscribe |
AWS IoT publishes to this topic after a AWS IoT Device Defender agent publishes
an unsuccessful message to
$aws/things/ |
AWS IoT Core Device Location topics
AWS IoT Core Device Location can resolve the measurement data from your device and provide an estimated location of your IoT devices. The measurement data from the device can include GNSS, Wi-Fi, cellular, and IP address. AWS IoT Core Device Location then chooses the measurement type that provides the best accuracy and solves the device location information. For more information, see AWS IoT Core Device Location and Resolving device location using AWS IoT Core Device Location MQTT topics.
| Topic | Allowed operations | Description |
|---|---|---|
|
$aws/device_location/ |
Publish |
A device publishes to this topic to get the scanned raw measurement data to be resolved by AWS IoT Core Device Location. |
|
$aws/device_location/ |
Subscribe |
AWS IoT Core Device Location publishes to this topic after it has resolved the device location successfully. |
|
$aws/device_location/ |
Subscribe |
AWS IoT Core Device Location publishes to this topic when it is unable to resolve the device location successfully due to 4xx errors. |
Event topics
The event messages are published when certain events occur. For example, events are generated by the registry when things are added, updated, or deleted. The table shows the various AWS IoT events and their reserved 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/job/ |
Subscribe |
AWS IoT publishes this message when a job is canceled. For more information, see Jobs events. |
$aws/events/job/jobID/cancellation_in_progress |
Subscribe |
AWS IoT publishes this message when a job cancellation is in progress. For more information, see Jobs events. |
|
$aws/events/job/ |
Subscribe |
AWS IoT publishes this message when a job has completed. For more information, see Jobs events. |
$aws/events/job/jobID/deleted |
Subscribe |
AWS IoT publishes this message when a job is deleted. For more information, see Jobs events. |
$aws/events/job/jobID/deletion_in_progress |
Subscribe |
AWS IoT publishes this message when a job deletion is in progress. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/canceled |
Subscribe |
AWS IoT publishes this message when a job execution is canceled. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/deleted |
Subscribe |
AWS IoT publishes this message when a job execution is deleted. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/failed |
Subscribe |
AWS IoT publishes this message when a job execution has failed. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/rejected |
Subscribe |
AWS IoT publishes this message when a job execution was rejected. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/removed |
Subscribe |
AWS IoT publishes this message when a job execution was removed. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/succeeded |
Subscribe |
AWS IoT publishes this message when a job execution succeeded. For more information, see Jobs events. |
$aws/events/jobExecution/jobID/timed_out |
Subscribe |
AWS IoT publishes this message when a job execution timed out. For more information, see Jobs events. |
|
$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
Note
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 expect to receive these response messages even if they haven't subscribed to them. These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules.
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, Receive |
AWS IoT publishes to this topic after a successful call to
$aws/certificates/create/ |
|
$aws/certificates/create/ |
Subscribe, Receive |
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, Receive |
AWS IoT publishes to this topic a successful call to
$aws/certificates/create-from-csr/ |
|
$aws/certificates/create-from-csr/ |
Subscribe, Receive |
AWS IoT publishes to this topic an unsuccessful call to
$aws/certificates/create-from-csr/ |
|
$aws/provisioning-templates/ |
Publish |
Publish to this topic to register a thing. |
|
$aws/provisioning-templates/ |
Subscribe, Receive |
AWS IoT publishes to this topic after a successful call to
$aws/provisioning-templates/ |
|
$aws/provisioning-templates/ |
Subscribe, Receive |
AWS IoT publishes to this topic after an unsuccessful call to
$aws/provisioning-templates/ |
Job topics
Note
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 expect to receive these response messages even if they haven't subscribed to them.
These response messages don't pass through the message broker and they can't
be subscribed to by other clients or rules. To subscribe to job activity related
messages, use the notify and notify-next
topics.
When subscribing to the job and jobExecution event topics for
your fleet-monitoring solution, you must first enable job and job execution events to receive any events on the cloud
side.
For more information, see Jobs device MQTT API operations.
| 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 to receive a response 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 to receive a response 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 to receive a response 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 NoteOnly the device that publishes to
$aws/things/ |
|
$aws/things/ |
Subscribe, Receive |
Devices subscribe to this topic to receive a response when an
NoteOnly the device that publishes to
$aws/things/ |
|
$aws/things/ |
Subscribe, Receive |
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 API operations. |
|
$aws/things/ |
Subscribe, Receive |
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 API operations. |
|
$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. |
Commands topics
Note
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 expect to receive these response messages even if they haven't subscribed to them.
These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules.
| Topic | Client operations allowed | Description |
|---|---|---|
|
$aws/commands/things/ $aws/commands/clients/ |
Subscribe, Receive |
Devices receive a message to this topic when a request is made
to start a command execution from the console or using the
|
|
$aws/commands/things/ $aws/commands/clients/ |
Publish |
Devices use the |
|
$aws/commands/things/ $aws/commands/clients/ |
Subscribe, Receive |
If the cloud service successfully processed the command execution result, AWS IoT Device Management publishes a response to the MQTT accepted topic. |
|
$aws/commands/things/ $aws/commands/clients/ |
Publish |
If the cloud service failed to process the command execution result, AWS IoT Device Management publishes a response to the MQTT rejected topic. |
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. |
MQTT-based file delivery topics
Note
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 expect to receive these response messages even if they haven't subscribed to them. These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules.
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, Receive |
AWS MQTT-based file delivery publishes to this topic if the "GetStream" request from a device is accepted. The payload contains the stream data. For more information, see Using AWS IoT MQTT-based file delivery in devices. |
|
$aws/things/ |
Publish |
A device publishes to this topic to perform a "GetStream" request. For more information, see Using AWS IoT MQTT-based file delivery in devices. |
|
$aws/things/ |
Subscribe, Receive |
AWS MQTT-based file delivery publishes to this topic if the "DescribeStream" request from a device is accepted. The payload contains the stream description. For more information, see Using AWS IoT MQTT-based file delivery in devices. |
|
$aws/things/ |
Publish |
A device publishes to this topic to perform a "DescribeStream" request. For more information, see Using AWS IoT MQTT-based file delivery in devices. |
|
$aws/things/ |
Subscribe, Receive |
AWS MQTT-based file delivery publishes to this topic if a "DescribeStream" or "GetStream" request from a device is rejected. For more information, see Using AWS IoT MQTT-based file delivery 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.
