AWS IoT

(1)

AWS IoT

API Reference

AWS IoT: API Reference

(2)

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

AWS IoT

AWS IoT provides secure, bi-directional communication between Internet-connected devices (such as sensors, actuators, embedded devices, or smart appliances) and the AWS cloud. You can discover your custom IoT-Data endpoint to communicate with, conﬁgure rules for data processing and integration with other services, organize resources associated with each device (Registry), conﬁgure logging, and create and manage policies and credentials to authenticate devices.

The service endpoints that expose this API are listed in AWS IoT Core Endpoints and Quotas. You must use the endpoint for the region that has the resources you want to access.

The service name used by AWS Signature Version 4 to sign the request is: execute-api.

For more information about how AWS IoT works, see the Developer Guide.

For information about how to use the credentials provider for AWS IoT, see Authorizing Direct Calls to AWS Services.

AWS IoT data

AWS IoT data enables secure, bi-directional communication between Internet-connected things (such as sensors, actuators, embedded devices, or smart appliances) and the AWS cloud. It implements a broker for applications and things to publish messages over HTTP (Publish) and retrieve, update, and delete shadows. A shadow is a persistent representation of your things and their state in the AWS cloud.

Find the endpoint address for actions in AWS IoT data by running this CLI command:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

The service name used by AWSSignature Version 4 to sign requests is: iotdevicegateway.

AWS IoT jobs data

AWS IoT Jobs is a service that allows you to define a set of jobs — remote operations that are sent to and executed on one or more devices connected to AWS IoT Core. For example, you can define a job that instructs a set of devices to download and install application or firmware updates, reboot, rotate certificates, or perform remote troubleshooting operations.

Find the endpoint address for actions in the AWS IoT jobs data plane by running this CLI command:

aws iot describe-endpoint --endpoint-type iot:Jobs

The service name used by AWS Signature Version 4 to sign requests is: IotLaserThingJobManagerService.

To create a job, you make a job document which is a description of the remote operations to be performed, and you specify a list of targets that should perform the operations. The targets can be individual things, thing groups or both.

(14)

AWS IoT Core Device Advisor

AWS IoT Jobs sends a message to inform the targets that a job is available. The target starts the execution of the job by downloading the job document, performing the operations it speciﬁes, and reporting its progress to AWS IoT Core. The Jobs service provides commands to track the progress of a job on a speciﬁc target and for all the targets of the job

AWS IoT Core Device Advisor

AWS IoT Core Device Advisor is a cloud-based, fully managed test capability for validating IoT devices during device software development. Device Advisor provides pre-built tests that you can use to validate IoT devices for reliable and secure connectivity with AWS IoT Core before deploying devices to production. By using Device Advisor, you can conﬁrm that your devices can connect to AWS IoT Core, follow security best practices and, if applicable, receive software updates from IoT Device Management.

You can also download signed qualiﬁcation reports to submit to the AWS Partner Network to get your device qualiﬁed for the AWS Partner Device Catalog without the need to send your device in and wait for it to be tested.

AWS IoT Fleet Hub

With Fleet Hub for AWS IoT Device Management you can build stand-alone web applications for monitoring the health of your device ﬂeets.

AWS IoT Secure Tunneling

AWS IoT Secure Tunneling creates remote connections to devices deployed in the ﬁeld.

For more information about how AWS IoT Secure Tunneling works, see AWS IoT Secure Tunneling.

(15)

Actions

The following actions are supported by AWS IoT:

• AcceptCertiﬁcateTransfer (p. 15)

• AddThingToBillingGroup (p. 17)

• AddThingToThingGroup (p. 20)

• AssociateTargetsWithJob (p. 23)

• AttachPolicy (p. 26)

• AttachPrincipalPolicy (p. 28)

• AttachSecurityProﬁle (p. 30)

• AttachThingPrincipal (p. 32)

• CancelAuditMitigationActionsTask (p. 34)

• CancelAuditTask (p. 36)

• CancelCertiﬁcateTransfer (p. 38)

• CancelDetectMitigationActionsTask (p. 40)

• CancelJob (p. 42)

• CancelJobExecution (p. 45)

• ClearDefaultAuthorizer (p. 48)

• ConﬁrmTopicRuleDestination (p. 50)

• CreateAuditSuppression (p. 52)

• CreateAuthorizer (p. 55)

• CreateBillingGroup (p. 59)

• CreateCertiﬁcateFromCsr (p. 62)

• CreateCustomMetric (p. 65)

• CreateDimension (p. 68)

• CreateDomainConﬁguration (p. 71)

• CreateDynamicThingGroup (p. 75)

• CreateFleetMetric (p. 79)

• CreateJob (p. 84)

• CreateJobTemplate (p. 90)

• CreateKeysAndCertiﬁcate (p. 95)

• CreateMitigationAction (p. 98)

• CreateOTAUpdate (p. 101)

• CreatePolicy (p. 107)

• CreatePolicyVersion (p. 110)

• CreateProvisioningClaim (p. 113)

• CreateProvisioningTemplate (p. 116)

• CreateProvisioningTemplateVersion (p. 120)

• CreateRoleAlias (p. 123)

• CreateScheduledAudit (p. 126)

• CreateSecurityProﬁle (p. 129)

• CreateStream (p. 133)

(16)

• CreateThing (p. 137)

• CreateThingGroup (p. 140)

• CreateThingType (p. 143)

• CreateTopicRule (p. 146)

• CreateTopicRuleDestination (p. 154)

• DeleteAccountAuditConﬁguration (p. 157)

• DeleteAuditSuppression (p. 159)

• DeleteAuthorizer (p. 161)

• DeleteBillingGroup (p. 163)

• DeleteCACertiﬁcate (p. 165)

• DeleteCertiﬁcate (p. 167)

• DeleteCustomMetric (p. 169)

• DeleteDimension (p. 171)

• DeleteDomainConﬁguration (p. 173)

• DeleteDynamicThingGroup (p. 175)

• DeleteFleetMetric (p. 177)

• DeleteJob (p. 179)

• DeleteJobExecution (p. 182)

• DeleteJobTemplate (p. 185)

• DeleteMitigationAction (p. 187)

• DeleteOTAUpdate (p. 189)

• DeletePolicy (p. 191)

• DeletePolicyVersion (p. 193)

• DeleteProvisioningTemplate (p. 195)

• DeleteProvisioningTemplateVersion (p. 197)

• DeleteRegistrationCode (p. 199)

• DeleteRoleAlias (p. 201)

• DeleteScheduledAudit (p. 203)

• DeleteSecurityProﬁle (p. 205)

• DeleteStream (p. 207)

• DeleteThing (p. 209)

• DeleteThingGroup (p. 211)

• DeleteThingType (p. 213)

• DeleteTopicRule (p. 215)

• DeleteTopicRuleDestination (p. 217)

• DeleteV2LoggingLevel (p. 219)

• DeprecateThingType (p. 221)

• DescribeAccountAuditConﬁguration (p. 223)

• DescribeAuditFinding (p. 225)

• DescribeAuditMitigationActionsTask (p. 228)

• DescribeAuditSuppression (p. 232)

• DescribeAuditTask (p. 235)

• DescribeAuthorizer (p. 238)

• DescribeBillingGroup (p. 240)

• DescribeCACertiﬁcate (p. 243)

• DescribeCertiﬁcate (p. 246)

(17)

• DescribeCustomMetric (p. 249)

• DescribeDefaultAuthorizer (p. 252)

• DescribeDetectMitigationActionsTask (p. 254)

• DescribeDimension (p. 257)

• DescribeDomainConﬁguration (p. 260)

• DescribeEndpoint (p. 263)

• DescribeEventConﬁgurations (p. 265)

• DescribeFleetMetric (p. 267)

• DescribeIndex (p. 271)

• DescribeJob (p. 274)

• DescribeJobExecution (p. 277)

• DescribeJobTemplate (p. 280)

• DescribeManagedJobTemplate (p. 284)

• DescribeMitigationAction (p. 287)

• DescribeProvisioningTemplate (p. 290)

• DescribeProvisioningTemplateVersion (p. 293)

• DescribeRoleAlias (p. 296)

• DescribeScheduledAudit (p. 298)

• DescribeSecurityProﬁle (p. 301)

• DescribeStream (p. 305)

• DescribeThing (p. 308)

• DescribeThingGroup (p. 311)

• DescribeThingRegistrationTask (p. 315)

• DescribeThingType (p. 319)

• DetachPolicy (p. 322)

• DetachPrincipalPolicy (p. 324)

• DetachSecurityProﬁle (p. 326)

• DetachThingPrincipal (p. 328)

• DisableTopicRule (p. 330)

• EnableTopicRule (p. 332)

• GetBehaviorModelTrainingSummaries (p. 334)

• GetBucketsAggregation (p. 336)

• GetCardinality (p. 340)

• GetEﬀectivePolicies (p. 343)

• GetIndexingConﬁguration (p. 346)

• GetJobDocument (p. 349)

• GetLoggingOptions (p. 351)

• GetOTAUpdate (p. 353)

• GetPercentiles (p. 357)

• GetPolicy (p. 360)

• GetPolicyVersion (p. 363)

• GetRegistrationCode (p. 366)

• GetStatistics (p. 368)

• GetTopicRule (p. 371)

• GetTopicRuleDestination (p. 379)

• GetV2LoggingOptions (p. 381)

(18)

• ListActiveViolations (p. 383)

• ListAttachedPolicies (p. 386)

• ListAuditFindings (p. 389)

• ListAuditMitigationActionsExecutions (p. 393)

• ListAuditMitigationActionsTasks (p. 396)

• ListAuditSuppressions (p. 399)

• ListAuditTasks (p. 402)

• ListAuthorizers (p. 405)

• ListBillingGroups (p. 408)

• ListCACertiﬁcates (p. 410)

• ListCertiﬁcates (p. 413)

• ListCertiﬁcatesByCA (p. 416)

• ListCustomMetrics (p. 419)

• ListDetectMitigationActionsExecutions (p. 421)

• ListDetectMitigationActionsTasks (p. 424)

• ListDimensions (p. 427)

• ListDomainConﬁgurations (p. 429)

• ListFleetMetrics (p. 432)

• ListIndices (p. 434)

• ListJobExecutionsForJob (p. 436)

• ListJobExecutionsForThing (p. 439)

• ListJobs (p. 442)

• ListJobTemplates (p. 445)

• ListManagedJobTemplates (p. 447)

• ListMitigationActions (p. 449)

• ListOTAUpdates (p. 451)

• ListOutgoingCertiﬁcates (p. 454)

• ListPolicies (p. 457)

• ListPolicyPrincipals (p. 460)

• ListPolicyVersions (p. 463)

• ListPrincipalPolicies (p. 465)

• ListPrincipalThings (p. 468)

• ListProvisioningTemplates (p. 471)

• ListProvisioningTemplateVersions (p. 473)

• ListRoleAliases (p. 476)

• ListScheduledAudits (p. 479)

• ListSecurityProﬁles (p. 481)

• ListSecurityProﬁlesForTarget (p. 484)

• ListStreams (p. 487)

• ListTagsForResource (p. 489)

• ListTargetsForPolicy (p. 491)

• ListTargetsForSecurityProﬁle (p. 494)

• ListThingGroups (p. 496)

• ListThingGroupsForThing (p. 499)

• ListThingPrincipals (p. 501)

• ListThingRegistrationTaskReports (p. 504)

(19)

• ListThingRegistrationTasks (p. 507)

• ListThings (p. 509)

• ListThingsInBillingGroup (p. 512)

• ListThingsInThingGroup (p. 514)

• ListThingTypes (p. 516)

• ListTopicRuleDestinations (p. 519)

• ListTopicRules (p. 521)

• ListV2LoggingLevels (p. 523)

• ListViolationEvents (p. 525)

• PutVeriﬁcationStateOnViolation (p. 529)

• RegisterCACertiﬁcate (p. 531)

• RegisterCertiﬁcate (p. 535)

• RegisterCertiﬁcateWithoutCA (p. 538)

• RegisterThing (p. 541)

• RejectCertiﬁcateTransfer (p. 544)

• RemoveThingFromBillingGroup (p. 547)

• RemoveThingFromThingGroup (p. 550)

• ReplaceTopicRule (p. 553)

• SearchIndex (p. 561)

• SetDefaultAuthorizer (p. 565)

• SetDefaultPolicyVersion (p. 568)

• SetLoggingOptions (p. 570)

• SetV2LoggingLevel (p. 572)

• SetV2LoggingOptions (p. 574)

• StartAuditMitigationActionsTask (p. 576)

• StartDetectMitigationActionsTask (p. 579)

• StartOnDemandAuditTask (p. 582)

• StartThingRegistrationTask (p. 584)

• StopThingRegistrationTask (p. 587)

• TagResource (p. 589)

• TestAuthorization (p. 591)

• TestInvokeAuthorizer (p. 595)

• TransferCertiﬁcate (p. 599)

• UntagResource (p. 602)

• UpdateAccountAuditConﬁguration (p. 604)

• UpdateAuditSuppression (p. 607)

• UpdateAuthorizer (p. 610)

• UpdateBillingGroup (p. 614)

• UpdateCACertiﬁcate (p. 617)

• UpdateCertiﬁcate (p. 620)

• UpdateCustomMetric (p. 623)

• UpdateDimension (p. 626)

• UpdateDomainConﬁguration (p. 629)

• UpdateDynamicThingGroup (p. 632)

• UpdateEventConﬁgurations (p. 635)

• UpdateFleetMetric (p. 637)

(20)

• UpdateIndexingConﬁguration (p. 641)

• UpdateJob (p. 644)

• UpdateMitigationAction (p. 648)

• UpdateProvisioningTemplate (p. 651)

• UpdateRoleAlias (p. 654)

• UpdateScheduledAudit (p. 657)

• UpdateSecurityProﬁle (p. 660)

• UpdateStream (p. 666)

• UpdateThing (p. 669)

• UpdateThingGroup (p. 672)

• UpdateThingGroupsForThing (p. 675)

• UpdateTopicRuleDestination (p. 678)

• ValidateSecurityProﬁleBehaviors (p. 681)

The following actions are supported by AWS IoT data:

• DeleteThingShadow (p. 684)

• GetRetainedMessage (p. 687)

• GetThingShadow (p. 690)

• ListNamedShadowsForThing (p. 693)

• ListRetainedMessages (p. 696)

• Publish (p. 699)

• UpdateThingShadow (p. 701)

The following actions are supported by AWS IoT jobs data:

• GetPendingJobExecutions (p. 707)

• StartNextPendingJobExecution (p. 710)

• UpdateJobExecution (p. 713)

The following actions are supported by AWS IoT Core Device Advisor:

• CreateSuiteDeﬁnition (p. 718)

• DeleteSuiteDeﬁnition (p. 721)

• GetEndpoint (p. 723)

• GetSuiteDeﬁnition (p. 725)

• GetSuiteRun (p. 728)

• GetSuiteRunReport (p. 732)

• ListSuiteDeﬁnitions (p. 734)

• ListSuiteRuns (p. 736)

• StartSuiteRun (p. 741)

• StopSuiteRun (p. 744)

• UpdateSuiteDeﬁnition (p. 750)

(21)

AWS IoT

The following actions are supported by AWS IoT Fleet Hub:

• CreateApplication (p. 753)

• DeleteApplication (p. 756)

• DescribeApplication (p. 758)

• ListApplications (p. 762)

• UpdateApplication (p. 770)

The following actions are supported by AWS IoT Secure Tunneling:

• CloseTunnel (p. 773)

• DescribeTunnel (p. 775)

• ListTunnels (p. 779)

• OpenTunnel (p. 781)

AWS IoT

The following actions are supported by AWS IoT:

• AcceptCertiﬁcateTransfer (p. 15)

• AddThingToBillingGroup (p. 17)

• AddThingToThingGroup (p. 20)

• AssociateTargetsWithJob (p. 23)

• AttachPolicy (p. 26)

• AttachPrincipalPolicy (p. 28)

• AttachSecurityProﬁle (p. 30)

• AttachThingPrincipal (p. 32)

• CancelAuditMitigationActionsTask (p. 34)

• CancelAuditTask (p. 36)

• CancelCertiﬁcateTransfer (p. 38)

• CancelDetectMitigationActionsTask (p. 40)

• CancelJob (p. 42)

• CancelJobExecution (p. 45)

• ClearDefaultAuthorizer (p. 48)

• ConﬁrmTopicRuleDestination (p. 50)

• CreateAuditSuppression (p. 52)

• CreateAuthorizer (p. 55)

• CreateBillingGroup (p. 59)

• CreateCertiﬁcateFromCsr (p. 62)

• CreateCustomMetric (p. 65)

(22)

AWS IoT

• CreateDimension (p. 68)

• CreateDomainConﬁguration (p. 71)

• CreateDynamicThingGroup (p. 75)

• CreateFleetMetric (p. 79)

• CreateJob (p. 84)

• CreateJobTemplate (p. 90)

• CreateKeysAndCertiﬁcate (p. 95)

• CreateMitigationAction (p. 98)

• CreateOTAUpdate (p. 101)

• CreatePolicy (p. 107)

• CreatePolicyVersion (p. 110)

• CreateProvisioningClaim (p. 113)

• CreateProvisioningTemplate (p. 116)

• CreateProvisioningTemplateVersion (p. 120)

• CreateRoleAlias (p. 123)

• CreateScheduledAudit (p. 126)

• CreateSecurityProﬁle (p. 129)

• CreateStream (p. 133)

• CreateThing (p. 137)

• CreateThingGroup (p. 140)

• CreateThingType (p. 143)

• CreateTopicRule (p. 146)

• CreateTopicRuleDestination (p. 154)

• DeleteAccountAuditConﬁguration (p. 157)

• DeleteAuditSuppression (p. 159)

• DeleteAuthorizer (p. 161)

• DeleteBillingGroup (p. 163)

• DeleteCACertiﬁcate (p. 165)

• DeleteCertiﬁcate (p. 167)

• DeleteCustomMetric (p. 169)

• DeleteDimension (p. 171)

• DeleteDomainConﬁguration (p. 173)

• DeleteDynamicThingGroup (p. 175)

• DeleteFleetMetric (p. 177)

• DeleteJob (p. 179)

• DeleteJobExecution (p. 182)

• DeleteJobTemplate (p. 185)

• DeleteMitigationAction (p. 187)

• DeleteOTAUpdate (p. 189)

• DeletePolicy (p. 191)

• DeletePolicyVersion (p. 193)

• DeleteProvisioningTemplate (p. 195)

• DeleteProvisioningTemplateVersion (p. 197)

• DeleteRegistrationCode (p. 199)

• DeleteRoleAlias (p. 201)

• DeleteScheduledAudit (p. 203)

(23)

AWS IoT

• DeleteSecurityProﬁle (p. 205)

• DeleteStream (p. 207)

• DeleteThing (p. 209)

• DeleteThingGroup (p. 211)

• DeleteThingType (p. 213)

• DeleteTopicRule (p. 215)

• DeleteTopicRuleDestination (p. 217)

• DeleteV2LoggingLevel (p. 219)

• DeprecateThingType (p. 221)

• DescribeAccountAuditConﬁguration (p. 223)

• DescribeAuditFinding (p. 225)

• DescribeAuditMitigationActionsTask (p. 228)

• DescribeAuditSuppression (p. 232)

• DescribeAuditTask (p. 235)

• DescribeAuthorizer (p. 238)

• DescribeBillingGroup (p. 240)

• DescribeCACertiﬁcate (p. 243)

• DescribeCertiﬁcate (p. 246)

• DescribeCustomMetric (p. 249)

• DescribeDefaultAuthorizer (p. 252)

• DescribeDetectMitigationActionsTask (p. 254)

• DescribeDimension (p. 257)

• DescribeDomainConﬁguration (p. 260)

• DescribeEndpoint (p. 263)

• DescribeEventConﬁgurations (p. 265)

• DescribeFleetMetric (p. 267)

• DescribeIndex (p. 271)

• DescribeJob (p. 274)

• DescribeJobTemplate (p. 280)

• DescribeManagedJobTemplate (p. 284)

• DescribeMitigationAction (p. 287)

• DescribeProvisioningTemplate (p. 290)

• DescribeProvisioningTemplateVersion (p. 293)

• DescribeRoleAlias (p. 296)

• DescribeScheduledAudit (p. 298)

• DescribeSecurityProﬁle (p. 301)

• DescribeStream (p. 305)

• DescribeThing (p. 308)

• DescribeThingGroup (p. 311)

• DescribeThingRegistrationTask (p. 315)

• DescribeThingType (p. 319)

• DetachPolicy (p. 322)

• DetachPrincipalPolicy (p. 324)

• DetachSecurityProﬁle (p. 326)

• DetachThingPrincipal (p. 328)

(24)

AWS IoT

• DisableTopicRule (p. 330)

• EnableTopicRule (p. 332)

• GetBehaviorModelTrainingSummaries (p. 334)

• GetBucketsAggregation (p. 336)

• GetCardinality (p. 340)

• GetEﬀectivePolicies (p. 343)

• GetIndexingConﬁguration (p. 346)

• GetJobDocument (p. 349)

• GetLoggingOptions (p. 351)

• GetOTAUpdate (p. 353)

• GetPercentiles (p. 357)

• GetPolicy (p. 360)

• GetPolicyVersion (p. 363)

• GetRegistrationCode (p. 366)

• GetStatistics (p. 368)

• GetTopicRule (p. 371)

• GetTopicRuleDestination (p. 379)

• GetV2LoggingOptions (p. 381)

• ListActiveViolations (p. 383)

• ListAttachedPolicies (p. 386)

• ListAuditFindings (p. 389)

• ListAuditMitigationActionsExecutions (p. 393)

• ListAuditMitigationActionsTasks (p. 396)

• ListAuditSuppressions (p. 399)

• ListAuditTasks (p. 402)

• ListAuthorizers (p. 405)

• ListBillingGroups (p. 408)

• ListCACertiﬁcates (p. 410)

• ListCertiﬁcates (p. 413)

• ListCertiﬁcatesByCA (p. 416)

• ListCustomMetrics (p. 419)

• ListDetectMitigationActionsExecutions (p. 421)

• ListDetectMitigationActionsTasks (p. 424)

• ListDimensions (p. 427)

• ListDomainConﬁgurations (p. 429)

• ListFleetMetrics (p. 432)

• ListIndices (p. 434)

• ListJobExecutionsForJob (p. 436)

• ListJobExecutionsForThing (p. 439)

• ListJobs (p. 442)

• ListJobTemplates (p. 445)

• ListManagedJobTemplates (p. 447)

• ListMitigationActions (p. 449)

• ListOTAUpdates (p. 451)

• ListOutgoingCertiﬁcates (p. 454)

• ListPolicies (p. 457)

(25)

AWS IoT

• ListPolicyPrincipals (p. 460)

• ListPolicyVersions (p. 463)

• ListPrincipalPolicies (p. 465)

• ListPrincipalThings (p. 468)

• ListProvisioningTemplates (p. 471)

• ListProvisioningTemplateVersions (p. 473)

• ListRoleAliases (p. 476)

• ListScheduledAudits (p. 479)

• ListSecurityProﬁles (p. 481)

• ListSecurityProﬁlesForTarget (p. 484)

• ListStreams (p. 487)

• ListTargetsForPolicy (p. 491)

• ListTargetsForSecurityProﬁle (p. 494)

• ListThingGroups (p. 496)

• ListThingGroupsForThing (p. 499)

• ListThingPrincipals (p. 501)

• ListThingRegistrationTaskReports (p. 504)

• ListThingRegistrationTasks (p. 507)

• ListThings (p. 509)

• ListThingsInBillingGroup (p. 512)

• ListThingsInThingGroup (p. 514)

• ListThingTypes (p. 516)

• ListTopicRuleDestinations (p. 519)

• ListTopicRules (p. 521)

• ListV2LoggingLevels (p. 523)

• ListViolationEvents (p. 525)

• PutVeriﬁcationStateOnViolation (p. 529)

• RegisterCACertiﬁcate (p. 531)

• RegisterCertiﬁcate (p. 535)

• RegisterCertiﬁcateWithoutCA (p. 538)

• RegisterThing (p. 541)

• RejectCertiﬁcateTransfer (p. 544)

• RemoveThingFromBillingGroup (p. 547)

• RemoveThingFromThingGroup (p. 550)

• ReplaceTopicRule (p. 553)

• SearchIndex (p. 561)

• SetDefaultAuthorizer (p. 565)

• SetDefaultPolicyVersion (p. 568)

• SetLoggingOptions (p. 570)

• SetV2LoggingLevel (p. 572)

• SetV2LoggingOptions (p. 574)

• StartAuditMitigationActionsTask (p. 576)

• StartDetectMitigationActionsTask (p. 579)

• StartOnDemandAuditTask (p. 582)

• StartThingRegistrationTask (p. 584)

(26)

AWS IoT

• StopThingRegistrationTask (p. 587)

• TestAuthorization (p. 591)

• TestInvokeAuthorizer (p. 595)

• TransferCertiﬁcate (p. 599)

• UpdateAccountAuditConﬁguration (p. 604)

• UpdateAuditSuppression (p. 607)

• UpdateAuthorizer (p. 610)

• UpdateBillingGroup (p. 614)

• UpdateCACertiﬁcate (p. 617)

• UpdateCertiﬁcate (p. 620)

• UpdateCustomMetric (p. 623)

• UpdateDimension (p. 626)

• UpdateDomainConﬁguration (p. 629)

• UpdateDynamicThingGroup (p. 632)

• UpdateEventConﬁgurations (p. 635)

• UpdateFleetMetric (p. 637)

• UpdateIndexingConﬁguration (p. 641)

• UpdateJob (p. 644)

• UpdateMitigationAction (p. 648)

• UpdateProvisioningTemplate (p. 651)

• UpdateRoleAlias (p. 654)

• UpdateScheduledAudit (p. 657)

• UpdateSecurityProﬁle (p. 660)

• UpdateStream (p. 666)

• UpdateThing (p. 669)

• UpdateThingGroup (p. 672)

• UpdateThingGroupsForThing (p. 675)

• UpdateTopicRuleDestination (p. 678)

• ValidateSecurityProﬁleBehaviors (p. 681)

(27)

AcceptCertiﬁcateTransfer

Service: AWS IoT

Accepts a pending certiﬁcate transfer. The default state of the certiﬁcate is INACTIVE.

To check for pending certificate transfers, call ListCertificates (p. 413) to enumerate your certificates.

Requires permission to access the AcceptCertiﬁcateTransfer action.

Request Syntax

PATCH /accept-certificate-transfer/certificateId?setAsActive=setAsActive HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

certiﬁcateId (p. 15)

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.) Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+

Required: Yes setAsActive (p. 15)

Speciﬁes whether the certiﬁcate is active.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500 InvalidRequestException

The request is not valid.

HTTP Status Code: 400

(28)

AcceptCertiﬁcateTransfer

ResourceNotFoundException

The speciﬁed resource does not exist.

HTTP Status Code: 404 ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503 ThrottlingException

The rate exceeds the limit.

TransferAlreadyCompletedException

You can't revert the certiﬁcate transfer because the transfer is already complete.

HTTP Status Code: 410 UnauthorizedException

You are not authorized to perform this operation.

AddThingToBillingGroup

Service: AWS IoT

Adds a thing to a billing group.

Requires permission to access the AddThingToBillingGroup action.

Request Syntax

PUT /billing-groups/addThingToBillingGroup HTTP/1.1 Content-type: application/json

{

"billingGroupArn": "string", "billingGroupName": "string", "thingArn": "string",

"thingName": "string"

}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

billingGroupArn (p. 17)

The ARN of the billing group.

Type: String Required: No

billingGroupName (p. 17)

The name of the billing group.

NoteThis call is asynchronous. It might take several seconds for the detachment to propagate.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: No thingArn (p. 17)

The ARN of the thing to be added to the billing group.

Type: String Required: No thingName (p. 17)

The name of the thing to be added to the billing group.

(30)

Type: String

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

Errors

HTTP Status Code: 400 ResourceNotFoundException

AddThingToThingGroup

Service: AWS IoT

Adds a thing to a thing group.

Requires permission to access the AddThingToThingGroup action.

Request Syntax

PUT /thing-groups/addThingToThingGroup HTTP/1.1 Content-type: application/json

{ "overrideDynamicGroups": boolean, "thingArn": "string",

"thingGroupArn": "string", "thingGroupName": "string", "thingName": "string"

}

URI Request Parameters

The request does not use any URI parameters.

Request Body

overrideDynamicGroups (p. 20)

Override dynamic thing groups with static thing groups when 10-group limit is reached. If a thing belongs to 10 thing groups, and one or more of those groups are dynamic thing groups, adding a thing to a static group removes the thing from the last dynamic group.

Type: Boolean Required: No thingArn (p. 20)

The ARN of the thing to add to a group.

Type: String Required: No thingGroupArn (p. 20)

The ARN of the group to which you are adding a thing.

Type: String Required: No thingGroupName (p. 20)

The name of the group to which you are adding a thing.

Type: String

(33)

Required: No thingName (p. 20)

The name of the thing to add to a group.

Type: String

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

Errors

AssociateTargetsWithJob

Service: AWS IoT

Associates a group with a continuous job. The following criteria must be met:

• The job must have been created with the targetSelection ﬁeld set to "CONTINUOUS".

• The job status must currently be "IN_PROGRESS".

• The total number of targets associated with a job must not exceed 100.

Requires permission to access the AssociateTargetsWithJob action.

Request Syntax

POST /jobs/jobId/targets?namespaceId=namespaceId HTTP/1.1 Content-type: application/json

{

"comment": "string", "targets": [ "string" ] }

URI Request Parameters

jobId (p. 23)

The unique identiﬁer you assigned to this job when it was created.

Pattern: [a-zA-Z0-9_-]+

Required: Yes namespaceId (p. 23)

The namespace used to indicate that a job is a customer-managed job.

When you specify a value for this parameter, AWS IoT Core sends jobs notiﬁcations to MQTT topics that contain the value in the following format.

$aws/things/THING_NAME/jobs/JOB_ID/notify-namespace-NAMESPACE_ID/

Note

The namespaceId feature is in public preview.

Request Body

comment (p. 23)

An optional comment string describing why the job was associated with the targets.

(36)

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No targets (p. 23)

A list of thing group ARNs that deﬁne the targets of the job.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "description": "string", "jobArn": "string", "jobId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

description (p. 24)

A short text description of the job.

Type: String

Pattern: [^\p{C}]+

jobArn (p. 24)

An ARN identifying the job.

Type: String jobId (p. 24)

The unique identiﬁer you assigned to this job when it was created.

Type: String

(37)

Errors

InvalidRequestException The request is not valid.

HTTP Status Code: 400 LimitExceededException

A limit has been exceeded.

AttachPolicy

Service: AWS IoT

Attaches the specified policy to the specified principal (certificate or other credential).

Requires permission to access the AttachPolicy action.

Request Syntax

PUT /target-policies/policyName HTTP/1.1 Content-type: application/json

{

"target": "string"

}

URI Request Parameters

policyName (p. 26)

The name of the policy to attach.

Pattern: [\w+=,.@-]+

Required: Yes

Request Body

target (p. 26)

The identity to which the policy is attached. For example, a thing group or a certiﬁcate.

Type: String Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(39)

AttachPolicy

AttachPrincipalPolicy

Service: AWS IoT

Attaches the specified policy to the specified principal (certificate or other credential).

Note: This action is deprecated. Please use AttachPolicy (p. 26) instead.

Requires permission to access the AttachPrincipalPolicy action.

Request Syntax

PUT /principal-policies/policyName HTTP/1.1 x-amzn-iot-principal: principal

URI Request Parameters

policyName (p. 28) The policy name.

Pattern: [\w+=,.@-]+

Required: Yes principal (p. 28)

The principal, which can be a certiﬁcate ARN (as returned from the CreateCertiﬁcate operation) or an Amazon Cognito ID.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(41)

AttachPrincipalPolicy

InvalidRequestException The request is not valid.

AttachSecurityProﬁle

Service: AWS IoT

Associates a Device Defender security profile with a thing group or this account. Each thing group or account can have up to five security profiles associated with it.

Requires permission to access the AttachSecurityProﬁle action.

Request Syntax

PUT /security-profiles/securityProfileName/targets?

securityProfileTargetArn=securityProfileTargetArn HTTP/1.1

URI Request Parameters

securityProﬁleName (p. 30)

The security proﬁle that is attached.

Required: Yes

securityProﬁleTargetArn (p. 30)

The ARN of the target (thing group) to which the security proﬁle is attached.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(43)

AttachSecurityProﬁle

HTTP Status Code: 400 VersionConﬂictException

An exception thrown when the version of an entity speciﬁed with the expectedVersion parameter does not match the latest version in the system.

AttachThingPrincipal

Service: AWS IoT

Attaches the specified principal to the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities.

Requires permission to access the AttachThingPrincipal action.

Request Syntax

PUT /things/thingName/principals HTTP/1.1 x-amzn-principal: principal

URI Request Parameters

principal (p. 32)

The principal, which can be a certiﬁcate ARN (as returned from the CreateCertiﬁcate operation) or an Amazon Cognito ID.

Required: Yes thingName (p. 32)

The name of the thing.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(45)

AttachThingPrincipal

CancelAuditMitigationActionsTask

Service: AWS IoT

Cancels a mitigation action task that is in progress. If the task is not in progress, an InvalidRequestException occurs.

Requires permission to access the CancelAuditMitigationActionsTask action.

Request Syntax

PUT /audit/mitigationactions/tasks/taskId/cancel HTTP/1.1

URI Request Parameters

taskId (p. 34)

The unique identiﬁer for the task that you want to cancel.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(47)

CancelAuditMitigationActionsTask

CancelAuditTask

Service: AWS IoT

Cancels an audit that is in progress. The audit can be either scheduled or on demand. If the audit isn't in progress, an "InvalidRequestException" occurs.

Requires permission to access the CancelAuditTask action.

Request Syntax

PUT /audit/tasks/taskId/cancel HTTP/1.1

URI Request Parameters

taskId (p. 36)

The ID of the audit you want to cancel. You can only cancel an audit that is "IN_PROGRESS".

Pattern: [a-zA-Z0-9\-]+

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(49)

CancelAuditTask

CancelCertiﬁcateTransfer

Service: AWS IoT

Cancels a pending transfer for the speciﬁed certiﬁcate.

Note Only the transfer source account can use this operation to cancel a transfer. (Transfer destinations can use RejectCertiﬁcateTransfer (p. 544) instead.) After transfer, AWS IoT returns the certiﬁcate to the source account in the INACTIVE state. After the destination account has accepted the transfer, the transfer cannot be cancelled.

After a certiﬁcate transfer is cancelled, the status of the certiﬁcate changes from PENDING_TRANSFER to INACTIVE.

Requires permission to access the CancelCertiﬁcateTransfer action.

Request Syntax

PATCH /cancel-certificate-transfer/certificateId HTTP/1.1

URI Request Parameters

certiﬁcateId (p. 38)

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.) Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(51)

CancelCertiﬁcateTransfer

TransferAlreadyCompletedException

You can't revert the certiﬁcate transfer because the transfer is already complete.

CancelDetectMitigationActionsTask

Service: AWS IoT

Cancels a Device Defender ML Detect mitigation action.

Requires permission to access the CancelDetectMitigationActionsTask action.

Request Syntax

PUT /detect/mitigationactions/tasks/taskId/cancel HTTP/1.1

URI Request Parameters

taskId (p. 40)

The unique identiﬁer of the task.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

AWS IoT

AWS IoT

API Reference

AWS IoT: API Reference

Table of Contents

Welcome

AWS IoT

AWS IoT data

AWS IoT jobs data

AWS IoT Core Device Advisor

AWS IoT Fleet Hub

AWS IoT Secure Tunneling

Actions

AWS IoT

AcceptCertiﬁcateTransfer

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AddThingToBillingGroup

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AddThingToThingGroup

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AssociateTargetsWithJob

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AttachPolicy

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AttachPrincipalPolicy

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AttachSecurityProﬁle

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

AttachThingPrincipal

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CancelAuditMitigationActionsTask

Request Syntax