AWS IoT

API Reference

AWS IoT: API Reference

Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
 AWS IoT API Reference

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 affiliated with, connected to, or sponsored by Amazon.
 AWS IoT API Reference

Table of Contents
Welcome ........................................................................................................................................... 1
AWS IoT .................................................................................................................................... 1
AWS IoT data ............................................................................................................................ 1
AWS IoT jobs data ...................................................................................................................... 1
AWS IoT Core Device Advisor ....................................................................................................... 2
AWS IoT Fleet Hub ..................................................................................................................... 2
AWS IoT Secure Tunneling .......................................................................................................... 2
Actions ............................................................................................................................................. 3
AWS IoT .................................................................................................................................... 9
AcceptCertificateTransfer .................................................................................................. 15
AddThingToBillingGroup ................................................................................................... 17
AddThingToThingGroup ................................................................................................... 19
AssociateTargetsWithJob .................................................................................................. 22
AttachPolicy ................................................................................................................... 25
AttachPrincipalPolicy ....................................................................................................... 27
AttachSecurityProfile ....................................................................................................... 29
AttachThingPrincipal ........................................................................................................ 31
CancelAuditMitigationActionsTask ...................................................................................... 33
CancelAuditTask .............................................................................................................. 35
CancelCertificateTransfer .................................................................................................. 37
CancelDetectMitigationActionsTask .................................................................................... 39
CancelJob ....................................................................................................................... 41
CancelJobExecution ......................................................................................................... 44
ClearDefaultAuthorizer ..................................................................................................... 47
ConfirmTopicRuleDestination ............................................................................................ 49
CreateAuditSuppression ................................................................................................... 51
CreateAuthorizer ............................................................................................................. 54
CreateBillingGroup .......................................................................................................... 58
CreateCertificateFromCsr .................................................................................................. 61
CreateCustomMetric ........................................................................................................ 64
CreateDimension ............................................................................................................. 67
CreateDomainConfiguration .............................................................................................. 70
CreateDynamicThingGroup ............................................................................................... 74
CreateFleetMetric ............................................................................................................ 78
CreateJob ....................................................................................................................... 83
CreateJobTemplate .......................................................................................................... 88
CreateKeysAndCertificate ................................................................................................. 93
CreateMitigationAction ..................................................................................................... 96
CreateOTAUpdate ............................................................................................................ 99
CreatePolicy .................................................................................................................. 105
CreatePolicyVersion ....................................................................................................... 108
CreateProvisioningClaim ................................................................................................. 111
CreateProvisioningTemplate ............................................................................................ 114
CreateProvisioningTemplateVersion .................................................................................. 118
CreateRoleAlias ............................................................................................................. 121
CreateScheduledAudit .................................................................................................... 124
CreateSecurityProfile ...................................................................................................... 127
CreateStream ................................................................................................................ 131
CreateThing .................................................................................................................. 135
CreateThingGroup ......................................................................................................... 138
CreateThingType ........................................................................................................... 141
CreateTopicRule ............................................................................................................ 144
CreateTopicRuleDestination ............................................................................................. 152
DeleteAccountAuditConfiguration .................................................................................... 155

iii
 AWS IoT API Reference

DeleteAuditSuppression .................................................................................................. 157

DeleteAuthorizer ........................................................................................................... 159
DeleteBillingGroup ......................................................................................................... 161
DeleteCACertificate ........................................................................................................ 163
DeleteCertificate ............................................................................................................ 165
DeleteCustomMetric ....................................................................................................... 167
DeleteDimension ........................................................................................................... 169
DeleteDomainConfiguration ............................................................................................ 171
DeleteDynamicThingGroup ............................................................................................. 173
DeleteFleetMetric .......................................................................................................... 175
DeleteJob ..................................................................................................................... 177
DeleteJobExecution ........................................................................................................ 180
DeleteJobTemplate ........................................................................................................ 183
DeleteMitigationAction ................................................................................................... 185
DeleteOTAUpdate .......................................................................................................... 187
DeletePolicy .................................................................................................................. 189
DeletePolicyVersion ....................................................................................................... 191
DeleteProvisioningTemplate ............................................................................................ 193
DeleteProvisioningTemplateVersion .................................................................................. 195
DeleteRegistrationCode .................................................................................................. 197
DeleteRoleAlias ............................................................................................................. 199
DeleteScheduledAudit .................................................................................................... 201
DeleteSecurityProfile ...................................................................................................... 203
DeleteStream ................................................................................................................ 205
DeleteThing .................................................................................................................. 207
DeleteThingGroup ......................................................................................................... 209
DeleteThingType ........................................................................................................... 211
DeleteTopicRule ............................................................................................................ 213
DeleteTopicRuleDestination ............................................................................................ 215
DeleteV2LoggingLevel .................................................................................................... 217
DeprecateThingType ...................................................................................................... 219
DescribeAccountAuditConfiguration ................................................................................. 221
DescribeAuditFinding ..................................................................................................... 223
DescribeAuditMitigationActionsTask ................................................................................. 226
DescribeAuditSuppression ............................................................................................... 230
DescribeAuditTask ......................................................................................................... 233
DescribeAuthorizer ......................................................................................................... 236
DescribeBillingGroup ...................................................................................................... 238
DescribeCACertificate ..................................................................................................... 241
DescribeCertificate ......................................................................................................... 244
DescribeCustomMetric .................................................................................................... 247
DescribeDefaultAuthorizer .............................................................................................. 250
DescribeDetectMitigationActionsTask ............................................................................... 252
DescribeDimension ........................................................................................................ 255
DescribeDomainConfiguration ......................................................................................... 258
DescribeEndpoint .......................................................................................................... 261
DescribeEventConfigurations ........................................................................................... 263
DescribeFleetMetric ........................................................................................................ 265
DescribeIndex ................................................................................................................ 269
DescribeJob .................................................................................................................. 272
DescribeJobExecution ..................................................................................................... 275
DescribeJobTemplate ..................................................................................................... 278
DescribeMitigationAction ................................................................................................ 282
DescribeProvisioningTemplate ......................................................................................... 285
DescribeProvisioningTemplateVersion ............................................................................... 288
DescribeRoleAlias .......................................................................................................... 291
DescribeScheduledAudit ................................................................................................. 293

iv
 AWS IoT API Reference

DescribeSecurityProfile ................................................................................................... 296

DescribeStream ............................................................................................................. 300
DescribeThing ............................................................................................................... 303
DescribeThingGroup ....................................................................................................... 306
DescribeThingRegistrationTask ........................................................................................ 310
DescribeThingType ......................................................................................................... 314
DetachPolicy ................................................................................................................. 317
DetachPrincipalPolicy ..................................................................................................... 319
DetachSecurityProfile ..................................................................................................... 321
DetachThingPrincipal ..................................................................................................... 323
DisableTopicRule ........................................................................................................... 325
EnableTopicRule ............................................................................................................ 327
GetBehaviorModelTrainingSummaries ............................................................................... 329
GetBucketsAggregation .................................................................................................. 331
GetCardinality ............................................................................................................... 335
GetEffectivePolicies ........................................................................................................ 338
GetIndexingConfiguration ............................................................................................... 341
GetJobDocument ........................................................................................................... 344
GetLoggingOptions ........................................................................................................ 346
GetOTAUpdate .............................................................................................................. 348
GetPercentiles ............................................................................................................... 352
GetPolicy ...................................................................................................................... 355
GetPolicyVersion ........................................................................................................... 358
GetRegistrationCode ...................................................................................................... 361
GetStatistics .................................................................................................................. 363
GetTopicRule ................................................................................................................. 366
GetTopicRuleDestination ................................................................................................. 373
GetV2LoggingOptions .................................................................................................... 375
ListActiveViolations ........................................................................................................ 377
ListAttachedPolicies ....................................................................................................... 380
ListAuditFindings ........................................................................................................... 383
ListAuditMitigationActionsExecutions ............................................................................... 387
ListAuditMitigationActionsTasks ....................................................................................... 390
ListAuditSuppressions .................................................................................................... 393
ListAuditTasks ............................................................................................................... 396
ListAuthorizers .............................................................................................................. 399
ListBillingGroups ........................................................................................................... 402
ListCACertificates ........................................................................................................... 404
ListCertificates .............................................................................................................. 407
ListCertificatesByCA ....................................................................................................... 410
ListCustomMetrics ......................................................................................................... 413
ListDetectMitigationActionsExecutions .............................................................................. 415
ListDetectMitigationActionsTasks ..................................................................................... 418
ListDimensions .............................................................................................................. 421
ListDomainConfigurations ............................................................................................... 423
ListFleetMetrics ............................................................................................................. 426
ListIndices .................................................................................................................... 428
ListJobExecutionsForJob ................................................................................................. 430
ListJobExecutionsForThing .............................................................................................. 433
ListJobs ........................................................................................................................ 436
ListJobTemplates ........................................................................................................... 439
ListMitigationActions ...................................................................................................... 441
ListOTAUpdates ............................................................................................................. 443
ListOutgoingCertificates ................................................................................................. 446
ListPolicies .................................................................................................................... 449
ListPolicyPrincipals ........................................................................................................ 452
ListPolicyVersions .......................................................................................................... 455

v
 AWS IoT API Reference

ListPrincipalPolicies ........................................................................................................ 457

ListPrincipalThings ......................................................................................................... 460
ListProvisioningTemplates ............................................................................................... 463
ListProvisioningTemplateVersions .................................................................................... 465
ListRoleAliases .............................................................................................................. 468
ListScheduledAudits ....................................................................................................... 471
ListSecurityProfiles ........................................................................................................ 473
ListSecurityProfilesForTarget ........................................................................................... 476
ListStreams ................................................................................................................... 479
ListTagsForResource ....................................................................................................... 481
ListTargetsForPolicy ....................................................................................................... 483
ListTargetsForSecurityProfile ........................................................................................... 486
ListThingGroups ............................................................................................................ 488
ListThingGroupsForThing ................................................................................................ 491
ListThingPrincipals ......................................................................................................... 493
ListThingRegistrationTaskReports .................................................................................... 496
ListThingRegistrationTasks .............................................................................................. 499
ListThings ..................................................................................................................... 501
ListThingsInBillingGroup ................................................................................................. 504
ListThingsInThingGroup .................................................................................................. 506
ListThingTypes .............................................................................................................. 508
ListTopicRuleDestinations ............................................................................................... 511
ListTopicRules ............................................................................................................... 513
ListV2LoggingLevels ...................................................................................................... 515
ListViolationEvents ........................................................................................................ 517
RegisterCACertificate ...................................................................................................... 520
RegisterCertificate ......................................................................................................... 524
RegisterCertificateWithoutCA .......................................................................................... 527
RegisterThing ................................................................................................................ 530
RejectCertificateTransfer ................................................................................................. 533
RemoveThingFromBillingGroup ....................................................................................... 536
RemoveThingFromThingGroup ........................................................................................ 538
ReplaceTopicRule ........................................................................................................... 541
SearchIndex .................................................................................................................. 549
SetDefaultAuthorizer ...................................................................................................... 553
SetDefaultPolicyVersion .................................................................................................. 556
SetLoggingOptions ........................................................................................................ 558
SetV2LoggingLevel ........................................................................................................ 560
SetV2LoggingOptions .................................................................................................... 562
StartAuditMitigationActionsTask ...................................................................................... 564
StartDetectMitigationActionsTask .................................................................................... 567
StartOnDemandAuditTask ............................................................................................... 570
StartThingRegistrationTask ............................................................................................. 572
StopThingRegistrationTask .............................................................................................. 575
TagResource .................................................................................................................. 577
TestAuthorization .......................................................................................................... 579
TestInvokeAuthorizer ...................................................................................................... 583
TransferCertificate ......................................................................................................... 587
UntagResource .............................................................................................................. 590
UpdateAccountAuditConfiguration ................................................................................... 592
UpdateAuditSuppression ................................................................................................ 595
UpdateAuthorizer .......................................................................................................... 598
UpdateBillingGroup ....................................................................................................... 601
UpdateCACertificate ....................................................................................................... 604
UpdateCertificate .......................................................................................................... 607
UpdateCustomMetric ..................................................................................................... 610
UpdateDimension .......................................................................................................... 613

vi
 AWS IoT API Reference

UpdateDomainConfiguration ........................................................................................... 616

UpdateDynamicThingGroup ............................................................................................ 619
UpdateEventConfigurations ............................................................................................ 622
UpdateFleetMetric ......................................................................................................... 624
UpdateIndexingConfiguration .......................................................................................... 628
UpdateJob .................................................................................................................... 631
UpdateMitigationAction .................................................................................................. 634
UpdateProvisioningTemplate ........................................................................................... 637
UpdateRoleAlias ............................................................................................................ 640
UpdateScheduledAudit ................................................................................................... 643
UpdateSecurityProfile .................................................................................................... 646
UpdateStream ............................................................................................................... 652
UpdateThing ................................................................................................................. 655
UpdateThingGroup ........................................................................................................ 658
UpdateThingGroupsForThing ........................................................................................... 661
UpdateTopicRuleDestination ........................................................................................... 664
ValidateSecurityProfileBehaviors ...................................................................................... 667
AWS IoT data ......................................................................................................................... 669
DeleteThingShadow ....................................................................................................... 670
GetRetainedMessage ...................................................................................................... 673
GetThingShadow ........................................................................................................... 676
ListNamedShadowsForThing ........................................................................................... 679
ListRetainedMessages ..................................................................................................... 682
Publish ......................................................................................................................... 685
UpdateThingShadow ...................................................................................................... 687
AWS IoT jobs data .................................................................................................................. 689
DescribeJobExecution ..................................................................................................... 690
GetPendingJobExecutions ............................................................................................... 693
StartNextPendingJobExecution ........................................................................................ 696
UpdateJobExecution ...................................................................................................... 699
AWS IoT Core Device Advisor ................................................................................................... 702
CreateSuiteDefinition ..................................................................................................... 704
DeleteSuiteDefinition ..................................................................................................... 707
GetSuiteDefinition ......................................................................................................... 709
GetSuiteRun .................................................................................................................. 712
GetSuiteRunReport ........................................................................................................ 716
ListSuiteDefinitions ........................................................................................................ 718
ListSuiteRuns ................................................................................................................ 720
ListTagsForResource ....................................................................................................... 723
StartSuiteRun ............................................................................................................... 725
StopSuiteRun ................................................................................................................ 728
TagResource .................................................................................................................. 730
UntagResource .............................................................................................................. 732
UpdateSuiteDefinition .................................................................................................... 734
AWS IoT Fleet Hub ................................................................................................................. 736
CreateApplication .......................................................................................................... 737
DeleteApplication .......................................................................................................... 740
DescribeApplication ....................................................................................................... 742
ListApplications ............................................................................................................. 746
ListTagsForResource ....................................................................................................... 748
TagResource .................................................................................................................. 750
UntagResource .............................................................................................................. 752
UpdateApplication ......................................................................................................... 754
AWS IoT Secure Tunneling ....................................................................................................... 756
CloseTunnel .................................................................................................................. 757
DescribeTunnel .............................................................................................................. 759
ListTagsForResource ....................................................................................................... 761

vii
 AWS IoT API Reference

ListTunnels ................................................................................................................... 763

OpenTunnel .................................................................................................................. 765
TagResource .................................................................................................................. 768
UntagResource .............................................................................................................. 770
Data Types .................................................................................................................................... 772
AWS IoT ................................................................................................................................ 777
AbortConfig .................................................................................................................. 782
AbortCriteria ................................................................................................................. 783
Action .......................................................................................................................... 785
ActiveViolation .............................................................................................................. 788
AddThingsToThingGroupParams ...................................................................................... 790
AggregationType ........................................................................................................... 791
AlertTarget ................................................................................................................... 792
Allowed ........................................................................................................................ 793
AssetPropertyTimestamp ................................................................................................ 794
AssetPropertyValue ........................................................................................................ 795
AssetPropertyVariant ..................................................................................................... 796
AttributePayload ........................................................................................................... 797
AuditCheckConfiguration ................................................................................................ 798
AuditCheckDetails .......................................................................................................... 799
AuditFinding ................................................................................................................. 801
AuditMitigationActionExecutionMetadata .......................................................................... 803
AuditMitigationActionsTaskMetadata ................................................................................ 805
AuditMitigationActionsTaskTarget .................................................................................... 806
AuditNotificationTarget .................................................................................................. 807
AuditSuppression ........................................................................................................... 808
AuditTaskMetadata ........................................................................................................ 810
AuthInfo ....................................................................................................................... 811
AuthorizerConfig ........................................................................................................... 812
AuthorizerDescription ..................................................................................................... 813
AuthorizerSummary ....................................................................................................... 815
AuthResult .................................................................................................................... 816
AwsJobAbortConfig ....................................................................................................... 817
AwsJobAbortCriteria ...................................................................................................... 818
AwsJobExecutionsRolloutConfig ...................................................................................... 820
AwsJobExponentialRolloutRate ........................................................................................ 821
AwsJobPresignedUrlConfig .............................................................................................. 822
AwsJobRateIncreaseCriteria ............................................................................................. 823
AwsJobTimeoutConfig .................................................................................................... 824
Behavior ....................................................................................................................... 825
BehaviorCriteria ............................................................................................................. 827
BehaviorModelTrainingSummary ...................................................................................... 829
BillingGroupMetadata .................................................................................................... 831
BillingGroupProperties ................................................................................................... 832
Bucket .......................................................................................................................... 833
BucketsAggregationType ................................................................................................ 834
CACertificate ................................................................................................................. 835
CACertificateDescription ................................................................................................. 836
Certificate ..................................................................................................................... 838
CertificateDescription ..................................................................................................... 840
CertificateValidity .......................................................................................................... 843
CloudwatchAlarmAction ................................................................................................. 844
CloudwatchLogsAction ................................................................................................... 845
CloudwatchMetricAction ................................................................................................. 846
CodeSigning ................................................................................................................. 848
CodeSigningCertificateChain ........................................................................................... 849
CodeSigningSignature .................................................................................................... 850

viii
 AWS IoT API Reference

Configuration ................................................................................................................ 851

CustomCodeSigning ....................................................................................................... 852
Denied ......................................................................................................................... 853
Destination ................................................................................................................... 854
DetectMitigationActionExecution ..................................................................................... 855
DetectMitigationActionsTaskStatistics ............................................................................... 857
DetectMitigationActionsTaskSummary .............................................................................. 858
DetectMitigationActionsTaskTarget .................................................................................. 860
DomainConfigurationSummary ........................................................................................ 861
DynamoDBAction .......................................................................................................... 862
DynamoDBv2Action ....................................................................................................... 864
EffectivePolicy ............................................................................................................... 865
ElasticsearchAction ........................................................................................................ 866
EnableIoTLoggingParams ................................................................................................ 867
ErrorInfo ...................................................................................................................... 868
ExplicitDeny .................................................................................................................. 869
ExponentialRolloutRate .................................................................................................. 870
Field ............................................................................................................................ 871
FileLocation .................................................................................................................. 872
FirehoseAction .............................................................................................................. 873
FleetMetricNameAndArn ................................................................................................. 874
GroupNameAndArn ........................................................................................................ 875
HttpAction .................................................................................................................... 876
HttpActionHeader .......................................................................................................... 878
HttpAuthorization .......................................................................................................... 879
HttpContext .................................................................................................................. 880
HttpUrlDestinationConfiguration ..................................................................................... 881
HttpUrlDestinationProperties .......................................................................................... 882
HttpUrlDestinationSummary ........................................................................................... 883
ImplicitDeny ................................................................................................................. 884
IotAnalyticsAction .......................................................................................................... 885
IotEventsAction ............................................................................................................. 886
IotSiteWiseAction .......................................................................................................... 888
Job .............................................................................................................................. 889
JobExecution ................................................................................................................. 893
JobExecutionsRolloutConfig ............................................................................................ 895
JobExecutionStatusDetails .............................................................................................. 896
JobExecutionSummary ................................................................................................... 897
JobExecutionSummaryForJob .......................................................................................... 899
JobExecutionSummaryForThing ....................................................................................... 900
JobProcessDetails .......................................................................................................... 901
JobSummary ................................................................................................................. 903
JobTemplateSummary .................................................................................................... 905
KafkaAction .................................................................................................................. 907
KeyPair ......................................................................................................................... 908
KinesisAction ................................................................................................................. 909
LambdaAction ............................................................................................................... 910
LoggingOptionsPayload .................................................................................................. 911
LogTarget ..................................................................................................................... 912
LogTargetConfiguration .................................................................................................. 913
MachineLearningDetectionConfig ..................................................................................... 914
MetricDimension ............................................................................................................ 915
MetricToRetain .............................................................................................................. 916
MetricValue ................................................................................................................... 917
MitigationAction ............................................................................................................ 919
MitigationActionIdentifier ............................................................................................... 920
MitigationActionParams .................................................................................................. 921

ix
 AWS IoT API Reference

MqttContext ................................................................................................................. 923

NonCompliantResource .................................................................................................. 924
OTAUpdateFile .............................................................................................................. 925
OTAUpdateInfo ............................................................................................................. 927
OTAUpdateSummary ...................................................................................................... 930
OutgoingCertificate ....................................................................................................... 931
PercentPair ................................................................................................................... 933
Policy ........................................................................................................................... 934
PolicyVersion ................................................................................................................ 935
PolicyVersionIdentifier .................................................................................................... 936
PresignedUrlConfig ........................................................................................................ 937
ProvisioningHook ........................................................................................................... 938
ProvisioningTemplateSummary ....................................................................................... 939
ProvisioningTemplateVersionSummary ............................................................................. 941
PublishFindingToSnsParams ............................................................................................ 942
PutAssetPropertyValueEntry ........................................................................................... 943
PutItemInput ................................................................................................................ 945
RateIncreaseCriteria ....................................................................................................... 946
RegistrationConfig ......................................................................................................... 947
RelatedResource ............................................................................................................ 948
ReplaceDefaultPolicyVersionParams ................................................................................. 949
RepublishAction ............................................................................................................ 950
ResourceIdentifier .......................................................................................................... 951
RoleAliasDescription ....................................................................................................... 953
S3Action ...................................................................................................................... 955
S3Destination ............................................................................................................... 956
S3Location ................................................................................................................... 957
SalesforceAction ............................................................................................................ 958
ScheduledAuditMetadata ................................................................................................ 959
SecurityProfileIdentifier .................................................................................................. 961
SecurityProfileTarget ...................................................................................................... 962
SecurityProfileTargetMapping .......................................................................................... 963
ServerCertificateSummary .............................................................................................. 964
SigningProfileParameter ................................................................................................. 965
SigV4Authorization ........................................................................................................ 966
SnsAction ..................................................................................................................... 967
SqsAction ..................................................................................................................... 968
StartSigningJobParameter .............................................................................................. 969
StatisticalThreshold ....................................................................................................... 970
Statistics ...................................................................................................................... 971
StepFunctionsAction ...................................................................................................... 973
Stream ......................................................................................................................... 974
StreamFile .................................................................................................................... 975
StreamInfo ................................................................................................................... 976
StreamSummary ............................................................................................................ 978
Tag .............................................................................................................................. 979
TaskStatistics ................................................................................................................ 980
TaskStatisticsForAuditCheck ............................................................................................ 982
TermsAggregation ......................................................................................................... 983
ThingAttribute .............................................................................................................. 984
ThingConnectivity .......................................................................................................... 986
ThingDocument ............................................................................................................. 987
ThingGroupDocument .................................................................................................... 989
ThingGroupIndexingConfiguration ................................................................................... 991
ThingGroupMetadata ..................................................................................................... 992
ThingGroupProperties .................................................................................................... 993
ThingIndexingConfiguration ............................................................................................ 994

x
 AWS IoT API Reference

ThingTypeDefinition ....................................................................................................... 996

ThingTypeMetadata ....................................................................................................... 997
ThingTypeProperties ...................................................................................................... 998
TimeoutConfig .............................................................................................................. 999
TimestreamAction ........................................................................................................ 1000
TimestreamDimension .................................................................................................. 1002
TimestreamTimestamp ................................................................................................. 1003
TlsContext .................................................................................................................. 1004
TopicRule .................................................................................................................... 1005
TopicRuleDestination .................................................................................................... 1007
TopicRuleDestinationConfiguration ................................................................................. 1009
TopicRuleDestinationSummary ...................................................................................... 1010
TopicRuleListItem ........................................................................................................ 1012
TopicRulePayload ......................................................................................................... 1013
TransferData ............................................................................................................... 1015
UpdateCACertificateParams ........................................................................................... 1016
UpdateDeviceCertificateParams ..................................................................................... 1017
ValidationError ............................................................................................................ 1018
ViolationEvent ............................................................................................................. 1019
ViolationEventAdditionalInfo ......................................................................................... 1021
ViolationEventOccurrenceRange ..................................................................................... 1022
VpcDestinationConfiguration ......................................................................................... 1023
VpcDestinationProperties .............................................................................................. 1024
VpcDestinationSummary ............................................................................................... 1025
AWS IoT data ....................................................................................................................... 1025
RetainedMessageSummary ............................................................................................ 1026
AWS IoT jobs data ................................................................................................................ 1026
JobExecution ............................................................................................................... 1028
JobExecutionState ....................................................................................................... 1031
JobExecutionSummary ................................................................................................. 1032
AWS IoT Core Device Advisor ................................................................................................. 1033
DeviceUnderTest .......................................................................................................... 1034
GroupResult ................................................................................................................ 1035
SuiteDefinitionConfiguration ......................................................................................... 1036
SuiteDefinitionInformation ............................................................................................ 1038
SuiteRunConfiguration ................................................................................................. 1040
SuiteRunInformation .................................................................................................... 1041
TestCaseRun ................................................................................................................ 1043
TestResult ................................................................................................................... 1045
AWS IoT Fleet Hub ............................................................................................................... 1045
ApplicationSummary .................................................................................................... 1046
AWS IoT Secure Tunneling ..................................................................................................... 1047
ConnectionState .......................................................................................................... 1048
DestinationConfig ........................................................................................................ 1049
Tag ............................................................................................................................ 1050
TimeoutConfig ............................................................................................................ 1051
Tunnel ........................................................................................................................ 1052
TunnelSummary .......................................................................................................... 1054
Common Parameters ..................................................................................................................... 1056

xi
 AWS IoT API Reference
AWS IoT

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, configure rules for data processing and integration with
other services, organize resources associated with each device (Registry), configure 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.

1
 AWS IoT API Reference
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 specifies, and
reporting its progress to AWS IoT Core. The Jobs service provides commands to track the progress of a
job on a specific 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 confirm 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 qualification reports to submit to the AWS Partner Network to get your
device qualified 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 fleets.

AWS IoT Secure Tunneling

AWS IoT Secure Tunnling creates remote connections to devices deployed in the field.

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

2
 AWS IoT API Reference

Actions
The following actions are supported by AWS IoT:

• AcceptCertificateTransfer (p. 15)

• AddThingToBillingGroup (p. 17)
• AddThingToThingGroup (p. 19)
• AssociateTargetsWithJob (p. 22)
• AttachPolicy (p. 25)
• AttachPrincipalPolicy (p. 27)
• AttachSecurityProfile (p. 29)
• AttachThingPrincipal (p. 31)
• CancelAuditMitigationActionsTask (p. 33)
• CancelAuditTask (p. 35)
• CancelCertificateTransfer (p. 37)
• CancelDetectMitigationActionsTask (p. 39)
• CancelJob (p. 41)
• CancelJobExecution (p. 44)
• ClearDefaultAuthorizer (p. 47)
• ConfirmTopicRuleDestination (p. 49)
• CreateAuditSuppression (p. 51)
• CreateAuthorizer (p. 54)
• CreateBillingGroup (p. 58)
• CreateCertificateFromCsr (p. 61)
• CreateCustomMetric (p. 64)
• CreateDimension (p. 67)
• CreateDomainConfiguration (p. 70)
• CreateDynamicThingGroup (p. 74)
• CreateFleetMetric (p. 78)
• CreateJob (p. 83)
• CreateJobTemplate (p. 88)
• CreateKeysAndCertificate (p. 93)
• CreateMitigationAction (p. 96)
• CreateOTAUpdate (p. 99)
• CreatePolicy (p. 105)
• CreatePolicyVersion (p. 108)
• CreateProvisioningClaim (p. 111)
• CreateProvisioningTemplate (p. 114)
• CreateProvisioningTemplateVersion (p. 118)
• CreateRoleAlias (p. 121)
• CreateScheduledAudit (p. 124)
• CreateSecurityProfile (p. 127)
• CreateStream (p. 131)
• CreateThing (p. 135)

3
 AWS IoT API Reference

• CreateThingGroup (p. 138)

• CreateThingType (p. 141)
• CreateTopicRule (p. 144)
• CreateTopicRuleDestination (p. 152)
• DeleteAccountAuditConfiguration (p. 155)
• DeleteAuditSuppression (p. 157)
• DeleteAuthorizer (p. 159)
• DeleteBillingGroup (p. 161)
• DeleteCACertificate (p. 163)
• DeleteCertificate (p. 165)
• DeleteCustomMetric (p. 167)
• DeleteDimension (p. 169)
• DeleteDomainConfiguration (p. 171)
• DeleteDynamicThingGroup (p. 173)
• DeleteFleetMetric (p. 175)
• DeleteJob (p. 177)
• DeleteJobExecution (p. 180)
• DeleteJobTemplate (p. 183)
• DeleteMitigationAction (p. 185)
• DeleteOTAUpdate (p. 187)
• DeletePolicy (p. 189)
• DeletePolicyVersion (p. 191)
• DeleteProvisioningTemplate (p. 193)
• DeleteProvisioningTemplateVersion (p. 195)
• DeleteRegistrationCode (p. 197)
• DeleteRoleAlias (p. 199)
• DeleteScheduledAudit (p. 201)
• DeleteSecurityProfile (p. 203)
• DeleteStream (p. 205)
• DeleteThing (p. 207)
• DeleteThingGroup (p. 209)
• DeleteThingType (p. 211)
• DeleteTopicRule (p. 213)
• DeleteTopicRuleDestination (p. 215)
• DeleteV2LoggingLevel (p. 217)
• DeprecateThingType (p. 219)
• DescribeAccountAuditConfiguration (p. 221)
• DescribeAuditFinding (p. 223)
• DescribeAuditMitigationActionsTask (p. 226)
• DescribeAuditSuppression (p. 230)
• DescribeAuditTask (p. 233)
• DescribeAuthorizer (p. 236)
• DescribeBillingGroup (p. 238)
• DescribeCACertificate (p. 241)
• DescribeCertificate (p. 244)
• DescribeCustomMetric (p. 247)

4
 AWS IoT API Reference

• DescribeDefaultAuthorizer (p. 250)

• DescribeDetectMitigationActionsTask (p. 252)
• DescribeDimension (p. 255)
• DescribeDomainConfiguration (p. 258)
• DescribeEndpoint (p. 261)
• DescribeEventConfigurations (p. 263)
• DescribeFleetMetric (p. 265)
• DescribeIndex (p. 269)
• DescribeJob (p. 272)
• DescribeJobExecution (p. 275)
• DescribeJobTemplate (p. 278)
• DescribeMitigationAction (p. 282)
• DescribeProvisioningTemplate (p. 285)
• DescribeProvisioningTemplateVersion (p. 288)
• DescribeRoleAlias (p. 291)
• DescribeScheduledAudit (p. 293)
• DescribeSecurityProfile (p. 296)
• DescribeStream (p. 300)
• DescribeThing (p. 303)
• DescribeThingGroup (p. 306)
• DescribeThingRegistrationTask (p. 310)
• DescribeThingType (p. 314)
• DetachPolicy (p. 317)
• DetachPrincipalPolicy (p. 319)
• DetachSecurityProfile (p. 321)
• DetachThingPrincipal (p. 323)
• DisableTopicRule (p. 325)
• EnableTopicRule (p. 327)
• GetBehaviorModelTrainingSummaries (p. 329)
• GetBucketsAggregation (p. 331)
• GetCardinality (p. 335)
• GetEffectivePolicies (p. 338)
• GetIndexingConfiguration (p. 341)
• GetJobDocument (p. 344)
• GetLoggingOptions (p. 346)
• GetOTAUpdate (p. 348)
• GetPercentiles (p. 352)
• GetPolicy (p. 355)
• GetPolicyVersion (p. 358)
• GetRegistrationCode (p. 361)
• GetStatistics (p. 363)
• GetTopicRule (p. 366)
• GetTopicRuleDestination (p. 373)
• GetV2LoggingOptions (p. 375)
• ListActiveViolations (p. 377)
• ListAttachedPolicies (p. 380)

5
 AWS IoT API Reference

• ListAuditFindings (p. 383)

• ListAuditMitigationActionsExecutions (p. 387)
• ListAuditMitigationActionsTasks (p. 390)
• ListAuditSuppressions (p. 393)
• ListAuditTasks (p. 396)
• ListAuthorizers (p. 399)
• ListBillingGroups (p. 402)
• ListCACertificates (p. 404)
• ListCertificates (p. 407)
• ListCertificatesByCA (p. 410)
• ListCustomMetrics (p. 413)
• ListDetectMitigationActionsExecutions (p. 415)
• ListDetectMitigationActionsTasks (p. 418)
• ListDimensions (p. 421)
• ListDomainConfigurations (p. 423)
• ListFleetMetrics (p. 426)
• ListIndices (p. 428)
• ListJobExecutionsForJob (p. 430)
• ListJobExecutionsForThing (p. 433)
• ListJobs (p. 436)
• ListJobTemplates (p. 439)
• ListMitigationActions (p. 441)
• ListOTAUpdates (p. 443)
• ListOutgoingCertificates (p. 446)
• ListPolicies (p. 449)
• ListPolicyPrincipals (p. 452)
• ListPolicyVersions (p. 455)
• ListPrincipalPolicies (p. 457)
• ListPrincipalThings (p. 460)
• ListProvisioningTemplates (p. 463)
• ListProvisioningTemplateVersions (p. 465)
• ListRoleAliases (p. 468)
• ListScheduledAudits (p. 471)
• ListSecurityProfiles (p. 473)
• ListSecurityProfilesForTarget (p. 476)
• ListStreams (p. 479)
• ListTagsForResource (p. 481)
• ListTargetsForPolicy (p. 483)
• ListTargetsForSecurityProfile (p. 486)
• ListThingGroups (p. 488)
• ListThingGroupsForThing (p. 491)
• ListThingPrincipals (p. 493)
• ListThingRegistrationTaskReports (p. 496)
• ListThingRegistrationTasks (p. 499)
• ListThings (p. 501)
• ListThingsInBillingGroup (p. 504)

6
 AWS IoT API Reference

• ListThingsInThingGroup (p. 506)

• ListThingTypes (p. 508)
• ListTopicRuleDestinations (p. 511)
• ListTopicRules (p. 513)
• ListV2LoggingLevels (p. 515)
• ListViolationEvents (p. 517)
• RegisterCACertificate (p. 520)
• RegisterCertificate (p. 524)
• RegisterCertificateWithoutCA (p. 527)
• RegisterThing (p. 530)
• RejectCertificateTransfer (p. 533)
• RemoveThingFromBillingGroup (p. 536)
• RemoveThingFromThingGroup (p. 538)
• ReplaceTopicRule (p. 541)
• SearchIndex (p. 549)
• SetDefaultAuthorizer (p. 553)
• SetDefaultPolicyVersion (p. 556)
• SetLoggingOptions (p. 558)
• SetV2LoggingLevel (p. 560)
• SetV2LoggingOptions (p. 562)
• StartAuditMitigationActionsTask (p. 564)
• StartDetectMitigationActionsTask (p. 567)
• StartOnDemandAuditTask (p. 570)
• StartThingRegistrationTask (p. 572)
• StopThingRegistrationTask (p. 575)
• TagResource (p. 577)
• TestAuthorization (p. 579)
• TestInvokeAuthorizer (p. 583)
• TransferCertificate (p. 587)
• UntagResource (p. 590)
• UpdateAccountAuditConfiguration (p. 592)
• UpdateAuditSuppression (p. 595)
• UpdateAuthorizer (p. 598)
• UpdateBillingGroup (p. 601)
• UpdateCACertificate (p. 604)
• UpdateCertificate (p. 607)
• UpdateCustomMetric (p. 610)
• UpdateDimension (p. 613)
• UpdateDomainConfiguration (p. 616)
• UpdateDynamicThingGroup (p. 619)
• UpdateEventConfigurations (p. 622)
• UpdateFleetMetric (p. 624)
• UpdateIndexingConfiguration (p. 628)
• UpdateJob (p. 631)
• UpdateMitigationAction (p. 634)
• UpdateProvisioningTemplate (p. 637)

7
 AWS IoT API Reference

• UpdateRoleAlias (p. 640)

• UpdateScheduledAudit (p. 643)
• UpdateSecurityProfile (p. 646)
• UpdateStream (p. 652)
• UpdateThing (p. 655)
• UpdateThingGroup (p. 658)
• UpdateThingGroupsForThing (p. 661)
• UpdateTopicRuleDestination (p. 664)
• ValidateSecurityProfileBehaviors (p. 667)

The following actions are supported by AWS IoT data:

• DeleteThingShadow (p. 670)

• GetRetainedMessage (p. 673)
• GetThingShadow (p. 676)
• ListNamedShadowsForThing (p. 679)
• ListRetainedMessages (p. 682)
• Publish (p. 685)
• UpdateThingShadow (p. 687)

The following actions are supported by AWS IoT jobs data:

• DescribeJobExecution (p. 690)

• GetPendingJobExecutions (p. 693)
• StartNextPendingJobExecution (p. 696)
• UpdateJobExecution (p. 699)

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

• CreateSuiteDefinition (p. 704)

• DeleteSuiteDefinition (p. 707)
• GetSuiteDefinition (p. 709)
• GetSuiteRun (p. 712)
• GetSuiteRunReport (p. 716)
• ListSuiteDefinitions (p. 718)
• ListSuiteRuns (p. 720)
• ListTagsForResource (p. 723)
• StartSuiteRun (p. 725)
• StopSuiteRun (p. 728)
• TagResource (p. 730)
• UntagResource (p. 732)
• UpdateSuiteDefinition (p. 734)

The following actions are supported by AWS IoT Fleet Hub:

• CreateApplication (p. 737)

• DeleteApplication (p. 740)

8
 AWS IoT API Reference
AWS IoT

• DescribeApplication (p. 742)

• ListApplications (p. 746)
• ListTagsForResource (p. 748)
• TagResource (p. 750)
• UntagResource (p. 752)
• UpdateApplication (p. 754)

The following actions are supported by AWS IoT Secure Tunneling:

• CloseTunnel (p. 757)

• DescribeTunnel (p. 759)
• ListTagsForResource (p. 761)
• ListTunnels (p. 763)
• OpenTunnel (p. 765)
• TagResource (p. 768)
• UntagResource (p. 770)

AWS IoT
The following actions are supported by AWS IoT:

• AcceptCertificateTransfer (p. 15)

• AddThingToBillingGroup (p. 17)
• AddThingToThingGroup (p. 19)
• AssociateTargetsWithJob (p. 22)
• AttachPolicy (p. 25)
• AttachPrincipalPolicy (p. 27)
• AttachSecurityProfile (p. 29)
• AttachThingPrincipal (p. 31)
• CancelAuditMitigationActionsTask (p. 33)
• CancelAuditTask (p. 35)
• CancelCertificateTransfer (p. 37)
• CancelDetectMitigationActionsTask (p. 39)
• CancelJob (p. 41)
• CancelJobExecution (p. 44)
• ClearDefaultAuthorizer (p. 47)
• ConfirmTopicRuleDestination (p. 49)
• CreateAuditSuppression (p. 51)
• CreateAuthorizer (p. 54)
• CreateBillingGroup (p. 58)
• CreateCertificateFromCsr (p. 61)
• CreateCustomMetric (p. 64)
• CreateDimension (p. 67)
• CreateDomainConfiguration (p. 70)
• CreateDynamicThingGroup (p. 74)
• CreateFleetMetric (p. 78)

9
 AWS IoT API Reference
AWS IoT

• CreateJob (p. 83)

• CreateJobTemplate (p. 88)
• CreateKeysAndCertificate (p. 93)
• CreateMitigationAction (p. 96)
• CreateOTAUpdate (p. 99)
• CreatePolicy (p. 105)
• CreatePolicyVersion (p. 108)
• CreateProvisioningClaim (p. 111)
• CreateProvisioningTemplate (p. 114)
• CreateProvisioningTemplateVersion (p. 118)
• CreateRoleAlias (p. 121)
• CreateScheduledAudit (p. 124)
• CreateSecurityProfile (p. 127)
• CreateStream (p. 131)
• CreateThing (p. 135)
• CreateThingGroup (p. 138)
• CreateThingType (p. 141)
• CreateTopicRule (p. 144)
• CreateTopicRuleDestination (p. 152)
• DeleteAccountAuditConfiguration (p. 155)
• DeleteAuditSuppression (p. 157)
• DeleteAuthorizer (p. 159)
• DeleteBillingGroup (p. 161)
• DeleteCACertificate (p. 163)
• DeleteCertificate (p. 165)
• DeleteCustomMetric (p. 167)
• DeleteDimension (p. 169)
• DeleteDomainConfiguration (p. 171)
• DeleteDynamicThingGroup (p. 173)
• DeleteFleetMetric (p. 175)
• DeleteJob (p. 177)
• DeleteJobExecution (p. 180)
• DeleteJobTemplate (p. 183)
• DeleteMitigationAction (p. 185)
• DeleteOTAUpdate (p. 187)
• DeletePolicy (p. 189)
• DeletePolicyVersion (p. 191)
• DeleteProvisioningTemplate (p. 193)
• DeleteProvisioningTemplateVersion (p. 195)
• DeleteRegistrationCode (p. 197)
• DeleteRoleAlias (p. 199)
• DeleteScheduledAudit (p. 201)
• DeleteSecurityProfile (p. 203)
• DeleteStream (p. 205)
• DeleteThing (p. 207)
• DeleteThingGroup (p. 209)

10
 AWS IoT API Reference
AWS IoT

• DeleteThingType (p. 211)

• DeleteTopicRule (p. 213)
• DeleteTopicRuleDestination (p. 215)
• DeleteV2LoggingLevel (p. 217)
• DeprecateThingType (p. 219)
• DescribeAccountAuditConfiguration (p. 221)
• DescribeAuditFinding (p. 223)
• DescribeAuditMitigationActionsTask (p. 226)
• DescribeAuditSuppression (p. 230)
• DescribeAuditTask (p. 233)
• DescribeAuthorizer (p. 236)
• DescribeBillingGroup (p. 238)
• DescribeCACertificate (p. 241)
• DescribeCertificate (p. 244)
• DescribeCustomMetric (p. 247)
• DescribeDefaultAuthorizer (p. 250)
• DescribeDetectMitigationActionsTask (p. 252)
• DescribeDimension (p. 255)
• DescribeDomainConfiguration (p. 258)
• DescribeEndpoint (p. 261)
• DescribeEventConfigurations (p. 263)
• DescribeFleetMetric (p. 265)
• DescribeIndex (p. 269)
• DescribeJob (p. 272)
• DescribeJobExecution (p. 275)
• DescribeJobTemplate (p. 278)
• DescribeMitigationAction (p. 282)
• DescribeProvisioningTemplate (p. 285)
• DescribeProvisioningTemplateVersion (p. 288)
• DescribeRoleAlias (p. 291)
• DescribeScheduledAudit (p. 293)
• DescribeSecurityProfile (p. 296)
• DescribeStream (p. 300)
• DescribeThing (p. 303)
• DescribeThingGroup (p. 306)
• DescribeThingRegistrationTask (p. 310)
• DescribeThingType (p. 314)
• DetachPolicy (p. 317)
• DetachPrincipalPolicy (p. 319)
• DetachSecurityProfile (p. 321)
• DetachThingPrincipal (p. 323)
• DisableTopicRule (p. 325)
• EnableTopicRule (p. 327)
• GetBehaviorModelTrainingSummaries (p. 329)
• GetBucketsAggregation (p. 331)
• GetCardinality (p. 335)

11
 AWS IoT API Reference
AWS IoT

• GetEffectivePolicies (p. 338)

• GetIndexingConfiguration (p. 341)
• GetJobDocument (p. 344)
• GetLoggingOptions (p. 346)
• GetOTAUpdate (p. 348)
• GetPercentiles (p. 352)
• GetPolicy (p. 355)
• GetPolicyVersion (p. 358)
• GetRegistrationCode (p. 361)
• GetStatistics (p. 363)
• GetTopicRule (p. 366)
• GetTopicRuleDestination (p. 373)
• GetV2LoggingOptions (p. 375)
• ListActiveViolations (p. 377)
• ListAttachedPolicies (p. 380)
• ListAuditFindings (p. 383)
• ListAuditMitigationActionsExecutions (p. 387)
• ListAuditMitigationActionsTasks (p. 390)
• ListAuditSuppressions (p. 393)
• ListAuditTasks (p. 396)
• ListAuthorizers (p. 399)
• ListBillingGroups (p. 402)
• ListCACertificates (p. 404)
• ListCertificates (p. 407)
• ListCertificatesByCA (p. 410)
• ListCustomMetrics (p. 413)
• ListDetectMitigationActionsExecutions (p. 415)
• ListDetectMitigationActionsTasks (p. 418)
• ListDimensions (p. 421)
• ListDomainConfigurations (p. 423)
• ListFleetMetrics (p. 426)
• ListIndices (p. 428)
• ListJobExecutionsForJob (p. 430)
• ListJobExecutionsForThing (p. 433)
• ListJobs (p. 436)
• ListJobTemplates (p. 439)
• ListMitigationActions (p. 441)
• ListOTAUpdates (p. 443)
• ListOutgoingCertificates (p. 446)
• ListPolicies (p. 449)
• ListPolicyPrincipals (p. 452)
• ListPolicyVersions (p. 455)
• ListPrincipalPolicies (p. 457)
• ListPrincipalThings (p. 460)
• ListProvisioningTemplates (p. 463)
• ListProvisioningTemplateVersions (p. 465)

12
 AWS IoT API Reference
AWS IoT

• ListRoleAliases (p. 468)

• ListScheduledAudits (p. 471)
• ListSecurityProfiles (p. 473)
• ListSecurityProfilesForTarget (p. 476)
• ListStreams (p. 479)
• ListTagsForResource (p. 481)
• ListTargetsForPolicy (p. 483)
• ListTargetsForSecurityProfile (p. 486)
• ListThingGroups (p. 488)
• ListThingGroupsForThing (p. 491)
• ListThingPrincipals (p. 493)
• ListThingRegistrationTaskReports (p. 496)
• ListThingRegistrationTasks (p. 499)
• ListThings (p. 501)
• ListThingsInBillingGroup (p. 504)
• ListThingsInThingGroup (p. 506)
• ListThingTypes (p. 508)
• ListTopicRuleDestinations (p. 511)
• ListTopicRules (p. 513)
• ListV2LoggingLevels (p. 515)
• ListViolationEvents (p. 517)
• RegisterCACertificate (p. 520)
• RegisterCertificate (p. 524)
• RegisterCertificateWithoutCA (p. 527)
• RegisterThing (p. 530)
• RejectCertificateTransfer (p. 533)
• RemoveThingFromBillingGroup (p. 536)
• RemoveThingFromThingGroup (p. 538)
• ReplaceTopicRule (p. 541)
• SearchIndex (p. 549)
• SetDefaultAuthorizer (p. 553)
• SetDefaultPolicyVersion (p. 556)
• SetLoggingOptions (p. 558)
• SetV2LoggingLevel (p. 560)
• SetV2LoggingOptions (p. 562)
• StartAuditMitigationActionsTask (p. 564)
• StartDetectMitigationActionsTask (p. 567)
• StartOnDemandAuditTask (p. 570)
• StartThingRegistrationTask (p. 572)
• StopThingRegistrationTask (p. 575)
• TagResource (p. 577)
• TestAuthorization (p. 579)
• TestInvokeAuthorizer (p. 583)
• TransferCertificate (p. 587)
• UntagResource (p. 590)
• UpdateAccountAuditConfiguration (p. 592)

13
 AWS IoT API Reference
AWS IoT

• UpdateAuditSuppression (p. 595)

• UpdateAuthorizer (p. 598)
• UpdateBillingGroup (p. 601)
• UpdateCACertificate (p. 604)
• UpdateCertificate (p. 607)
• UpdateCustomMetric (p. 610)
• UpdateDimension (p. 613)
• UpdateDomainConfiguration (p. 616)
• UpdateDynamicThingGroup (p. 619)
• UpdateEventConfigurations (p. 622)
• UpdateFleetMetric (p. 624)
• UpdateIndexingConfiguration (p. 628)
• UpdateJob (p. 631)
• UpdateMitigationAction (p. 634)
• UpdateProvisioningTemplate (p. 637)
• UpdateRoleAlias (p. 640)
• UpdateScheduledAudit (p. 643)
• UpdateSecurityProfile (p. 646)
• UpdateStream (p. 652)
• UpdateThing (p. 655)
• UpdateThingGroup (p. 658)
• UpdateThingGroupsForThing (p. 661)
• UpdateTopicRuleDestination (p. 664)
• ValidateSecurityProfileBehaviors (p. 667)

14
 AWS IoT API Reference
AcceptCertificateTransfer

AcceptCertificateTransfer
Service: AWS IoT

Accepts a pending certificate transfer. The default state of the certificate is INACTIVE.

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

Requires permission to access the AcceptCertificateTransfer action.

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

URI Request Parameters

The request uses the following URI parameters.

certificateId (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)

Specifies whether the certificate 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

15
 AWS IoT API Reference
AcceptCertificateTransfer

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

TransferAlreadyCompletedException

You can't revert the certificate transfer because the transfer is already complete.

HTTP Status Code: 410

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

16
 AWS IoT API Reference
AddThingToBillingGroup

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.

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.

Type: String

17
 AWS IoT API Reference
AddThingToBillingGroup

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

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

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

18
 AWS IoT API Reference
AddThingToThingGroup

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
The request accepts the following data in JSON format.

overrideDynamicGroups (p. 19)

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. 19)

The ARN of the thing to add to a group.

Type: String

Required: No
thingGroupArn (p. 19)

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

Type: String

Required: No
thingGroupName (p. 19)

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

Type: String

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

19
 AWS IoT API Reference
AddThingToThingGroup

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

Required: No
thingName (p. 19)

The name of the thing to add to a group.

Type: String

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

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

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

20
 AWS IoT API Reference
AddThingToThingGroup

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

21
 AWS IoT API Reference
AssociateTargetsWithJob

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 field 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

The request uses the following URI parameters.

jobId (p. 22)

The unique identifier you assigned to this job when it was created.

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

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

Required: Yes
namespaceId (p. 22)

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 notifications 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.

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

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

Request Body
The request accepts the following data in JSON format.

comment (p. 22)

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

22
 AWS IoT API Reference
AssociateTargetsWithJob

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
targets (p. 22)

A list of thing group ARNs that define the targets of the job.

Type: Array of strings

Array Members: Minimum number of 1 item.

Length Constraints: Maximum length of 2048.

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. 23)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
jobArn (p. 23)

An ARN identifying the job.

Type: String
jobId (p. 23)

The unique identifier you assigned to this job when it was created.

Type: String

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

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

23
 AWS IoT API Reference
AssociateTargetsWithJob

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

24
 AWS IoT API Reference
AttachPolicy

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

The request uses the following URI parameters.

policyName (p. 25)

The name of the policy to attach.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

target (p. 25)

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

Type: String

Required: Yes

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.

25
 AWS IoT API Reference
AttachPolicy

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

26
 AWS IoT API Reference
AttachPrincipalPolicy

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. 25) 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

The request uses the following URI parameters.

policyName (p. 27)

The policy name.

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

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

Required: Yes
principal (p. 27)

The principal, which can be a certificate ARN (as returned from the CreateCertificate operation) or an
Amazon Cognito ID.

Required: Yes

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

27
 AWS IoT API Reference
AttachPrincipalPolicy

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

28
 AWS IoT API Reference
AttachSecurityProfile

AttachSecurityProfile
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 AttachSecurityProfile action.

Request Syntax
PUT /security-profiles/securityProfileName/targets?
securityProfileTargetArn=securityProfileTargetArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

securityProfileName (p. 29)

The security profile that is attached.

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

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

Required: Yes
securityProfileTargetArn (p. 29)

The ARN of the target (thing group) to which the security profile is attached.

Required: Yes

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.

29
 AWS IoT API Reference
AttachSecurityProfile

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

30
 AWS IoT API Reference
AttachThingPrincipal

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

The request uses the following URI parameters.

principal (p. 31)

The principal, which can be a certificate ARN (as returned from the CreateCertificate operation) or an
Amazon Cognito ID.

Required: Yes
thingName (p. 31)

The name of the thing.

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

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

Required: Yes

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.

31
 AWS IoT API Reference
AttachThingPrincipal

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

32
 AWS IoT API Reference
CancelAuditMitigationActionsTask

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

The request uses the following URI parameters.

taskId (p. 33)

The unique identifier for the task that you want to cancel.

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

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

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

33
 AWS IoT API Reference
CancelAuditMitigationActionsTask

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

34
 AWS IoT API Reference
CancelAuditTask

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

The request uses the following URI parameters.

taskId (p. 35)

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

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

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

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

35
 AWS IoT API Reference
CancelAuditTask

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

36
 AWS IoT API Reference
CancelCertificateTransfer

CancelCertificateTransfer
Service: AWS IoT

Cancels a pending transfer for the specified certificate.

Note Only the transfer source account can use this operation to cancel a transfer. (Transfer destinations
can use RejectCertificateTransfer (p. 533) instead.) After transfer, AWS IoT returns the certificate to
the source account in the INACTIVE state. After the destination account has accepted the transfer, the
transfer cannot be cancelled.

After a certificate transfer is cancelled, the status of the certificate changes from PENDING_TRANSFER to
INACTIVE.

Requires permission to access the CancelCertificateTransfer action.

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

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 37)

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
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.

37
 AWS IoT API Reference
CancelCertificateTransfer

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

TransferAlreadyCompletedException

You can't revert the certificate transfer because the transfer is already complete.

HTTP Status Code: 410

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

38
 AWS IoT API Reference
CancelDetectMitigationActionsTask

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

The request uses the following URI parameters.

taskId (p. 39)

The unique identifier of the task.

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

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

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

39
 AWS IoT API Reference
CancelDetectMitigationActionsTask

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

40
 AWS IoT API Reference
CancelJob

CancelJob
Service: AWS IoT

Cancels a job.

Requires permission to access the CancelJob action.

Request Syntax
PUT /jobs/jobId/cancel?force=force HTTP/1.1
Content-type: application/json

{
"comment": "string",
"reasonCode": "string"
}

URI Request Parameters

The request uses the following URI parameters.

force (p. 41)

(Optional) If true job executions with status "IN_PROGRESS" and "QUEUED" are canceled, otherwise
only job executions with status "QUEUED" are canceled. The default is false.

Canceling a job which is "IN_PROGRESS", will cause a device which is executing the job to be unable
to update the job execution status. Use caution and ensure that each device executing a job which is
canceled is able to recover to a valid state.
jobId (p. 41)

The unique identifier you assigned to this job when it was created.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

comment (p. 41)

An optional comment string describing why the job was canceled.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
reasonCode (p. 41)

(Optional)A reason code string that explains why the job was canceled.

41
 AWS IoT API Reference
CancelJob

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Upper}\p{Digit}_]+

Required: No

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. 42)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
jobArn (p. 42)

The job ARN.

Type: String
jobId (p. 42)

The unique identifier you assigned to this job when it was created.

Type: String

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

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

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

42
 AWS IoT API Reference
CancelJob

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

43
 AWS IoT API Reference
CancelJobExecution

CancelJobExecution
Service: AWS IoT

Cancels the execution of a job for a given thing.

Requires permission to access the CancelJobExecution action.

Request Syntax
PUT /things/thingName/jobs/jobId/cancel?force=force HTTP/1.1
Content-type: application/json

{
"expectedVersion": number,
"statusDetails": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

force (p. 44)

(Optional) If true the job execution will be canceled if it has status IN_PROGRESS or QUEUED,
otherwise the job execution will be canceled only if it has status QUEUED. If you attempt
to cancel a job execution that is IN_PROGRESS, and you do not set force to true, then an
InvalidStateTransitionException will be thrown. The default is false.

Canceling a job execution which is "IN_PROGRESS", will cause the device to be unable to update the
job execution status. Use caution and ensure that the device is able to recover to a valid state.
jobId (p. 44)

The ID of the job to be canceled.

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

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

Required: Yes
thingName (p. 44)

The name of the thing whose execution of the job will be canceled.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

expectedVersion (p. 44)

(Optional) The expected current version of the job execution. Each time you update the job
execution, its version is incremented. If the version of the job execution stored in Jobs does not

44
 AWS IoT API Reference
CancelJobExecution

match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains
the current job execution status data is returned. (This makes it unnecessary to perform a separate
DescribeJobExecution request in order to obtain the job execution status data.)

Type: Long

Required: No
statusDetails (p. 44)

A collection of name/value pairs that describe the status of the job execution. If not specified, the
statusDetails are unchanged. You can specify at most 10 name/value pairs.

Type: String to string map

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

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

Value Length Constraints: Minimum length of 1.

Value Pattern: [^\p{C}]+

Required: No

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
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

InvalidStateTransitionException

An attempt was made to change to an invalid state, for example by deleting a job or a job execution
which is "IN_PROGRESS" without setting the force parameter.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

45
 AWS IoT API Reference
CancelJobExecution

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

46
 AWS IoT API Reference
ClearDefaultAuthorizer

ClearDefaultAuthorizer
Service: AWS IoT

Clears the default authorizer.

Requires permission to access the ClearDefaultAuthorizer action.

Request Syntax
DELETE /default-authorizer HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

47
 AWS IoT API Reference
ClearDefaultAuthorizer

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

48
 AWS IoT API Reference
ConfirmTopicRuleDestination

ConfirmTopicRuleDestination
Service: AWS IoT

Confirms a topic rule destination. When you create a rule requiring a destination, AWS IoT sends a
confirmation message to the endpoint or base address you specify. The message includes a token which
you pass back when calling ConfirmTopicRuleDestination to confirm that you own or have access
to the endpoint.

Requires permission to access the ConfirmTopicRuleDestination action.

Request Syntax
GET /confirmdestination/confirmationToken+ HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

confirmationToken (p. 49)

The token used to confirm ownership or access to the topic rule confirmation URL.

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

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

49
 AWS IoT API Reference
ConfirmTopicRuleDestination

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

50
 AWS IoT API Reference
CreateAuditSuppression

CreateAuditSuppression
Service: AWS IoT

Creates a Device Defender audit suppression.

Requires permission to access the CreateAuditSuppression action.

Request Syntax
POST /audit/suppressions/create HTTP/1.1
Content-type: application/json

{
"checkName": "string",
"clientRequestToken": "string",
"description": "string",
"expirationDate": number,
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"suppressIndefinitely": boolean
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

checkName (p. 51)

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: Yes
clientRequestToken (p. 51)

Each audit supression must have a unique client request token. If you try to create a new audit
suppression with the same token as one that already exists, an exception occurs. If you omit this
value, AWS SDKs will automatically generate a unique client request.

Type: String

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

51
 AWS IoT API Reference
CreateAuditSuppression

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

Required: Yes
description (p. 51)

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No
expirationDate (p. 51)

The epoch timestamp in seconds at which this suppression expires.

Type: Timestamp

Required: No
resourceIdentifier (p. 51)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: Yes
suppressIndefinitely (p. 51)

Indicates whether a suppression should exist indefinitely or not.

Type: Boolean

Required: No

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

52
 AWS IoT API Reference
CreateAuditSuppression

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

53
 AWS IoT API Reference
CreateAuthorizer

CreateAuthorizer
Service: AWS IoT

Creates an authorizer.

Requires permission to access the CreateAuthorizer action.

Request Syntax
POST /authorizer/authorizerName HTTP/1.1
Content-type: application/json

{
"authorizerFunctionArn": "string",
"signingDisabled": boolean,
"status": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"tokenKeyName": "string",
"tokenSigningPublicKeys": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

authorizerName (p. 54)

The authorizer name.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

authorizerFunctionArn (p. 54)

The ARN of the authorizer's Lambda function.

Type: String

Length Constraints: Maximum length of 2048.

Required: Yes
signingDisabled (p. 54)

Specifies whether AWS IoT validates the token signature in an authorization request.

54
 AWS IoT API Reference
CreateAuthorizer

Type: Boolean

Required: No
status (p. 54)

The status of the create authorizer request.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
tags (p. 54)

Metadata which can be used to manage the custom authorizer.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...
For the CLI command-line parameter use format: &&tags "key1=value1&key2=value2..."
For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Type: Array of Tag (p. 979) objects

Required: No
tokenKeyName (p. 54)

The name of the token key used to extract the token from the HTTP headers.

Type: String

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

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

Required: No
tokenSigningPublicKeys (p. 54)

The public keys used to verify the digital signature returned by your custom authentication service.

Type: String to string map

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

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

Value Length Constraints: Maximum length of 5120.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizerArn": "string",
"authorizerName": "string"
}

55
 AWS IoT API Reference
CreateAuthorizer

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.

authorizerArn (p. 55)

The authorizer ARN.

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 55)

The authorizer's name.

Type: String

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

Pattern: [\w=,@-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

56
 AWS IoT API Reference
CreateAuthorizer

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

57
 AWS IoT API Reference
CreateBillingGroup

CreateBillingGroup
Service: AWS IoT

Creates a billing group.

Requires permission to access the CreateBillingGroup action.

Request Syntax
POST /billing-groups/billingGroupName HTTP/1.1
Content-type: application/json

{
"billingGroupProperties": {
"billingGroupDescription": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

billingGroupName (p. 58)

The name you wish to give to the billing group.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

billingGroupProperties (p. 58)

The properties of the billing group.

Type: BillingGroupProperties (p. 832) object

Required: No
tags (p. 58)

Metadata which can be used to manage the billing group.

Type: Array of Tag (p. 979) objects

Required: No

58
 AWS IoT API Reference
CreateBillingGroup

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"billingGroupArn": "string",
"billingGroupId": "string",
"billingGroupName": "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.

billingGroupArn (p. 59)

The ARN of the billing group.

Type: String
billingGroupId (p. 59)

The ID of the billing group.

Type: String

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

Pattern: [a-zA-Z0-9\-]+
billingGroupName (p. 59)

The name you gave to the billing group.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

59
 AWS IoT API Reference
CreateBillingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

60
 AWS IoT API Reference
CreateCertificateFromCsr

CreateCertificateFromCsr
Service: AWS IoT

Creates an X.509 certificate using the specified certificate signing request.

Note: The CSR must include a public key that is either an RSA key with a length of at least 2048 bits or
an ECC key from NIST P-256 or NIST P-384 curves.

Note: Reusing the same certificate signing request (CSR) results in a distinct certificate.

Requires permission to access the CreateCertificateFromCsr action.

You can create multiple certificates in a batch by creating a directory, copying multiple .csr files into that
directory, and then specifying that directory on the command line. The following commands show how
to create a batch of certificates given a batch of CSRs.

Assuming a set of CSRs are located inside of the directory my-csr-directory:

On Linux and OS X, the command is:

$ ls my-csr-directory/ | xargs -I {} aws iot create-certificate-from-csr --certificate-signing-request file://

my-csr-directory/{}

This command lists all of the CSRs in my-csr-directory and pipes each CSR file name to the aws iot
create-certificate-from-csr AWS CLI command to create a certificate for the corresponding CSR.

The aws iot create-certificate-from-csr part of the command can also be run in parallel to speed up the
certificate creation process:

$ ls my-csr-directory/ | xargs -P 10 -I {} aws iot create-certificate-from-csr --certificate-signing-request

file://my-csr-directory/{}

On Windows PowerShell, the command to create certificates for all CSRs in my-csr-directory is:

> ls -Name my-csr-directory | %{aws iot create-certificate-from-csr --certificate-signing-request file://

my-csr-directory/$_}

On a Windows command prompt, the command to create certificates for all CSRs in my-csr-directory is:

> forfiles /p my-csr-directory /c "cmd /c aws iot create-certificate-from-csr --certificate-signing-request

file://@path"

Request Syntax
POST /certificates?setAsActive=setAsActive HTTP/1.1
Content-type: application/json

{
"certificateSigningRequest": "string"
}

URI Request Parameters

The request uses the following URI parameters.

setAsActive (p. 61)

Specifies whether the certificate is active.

61
 AWS IoT API Reference
CreateCertificateFromCsr

Request Body
The request accepts the following data in JSON format.

certificateSigningRequest (p. 61)

The certificate signing request (CSR).

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateArn": "string",
"certificateId": "string",
"certificatePem": "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.

certificateArn (p. 62)

The Amazon Resource Name (ARN) of the certificate. You can use the ARN as a principal for policy
operations.

Type: String
certificateId (p. 62)

The ID of the certificate. Certificate management operations only take a certificateId.

Type: String

Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+
certificatePem (p. 62)

The certificate data, in PEM format.

Type: String

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

Errors
InternalFailureException

An unexpected error has occurred.

62
 AWS IoT API Reference
CreateCertificateFromCsr

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

63
 AWS IoT API Reference
CreateCustomMetric

CreateCustomMetric
Service: AWS IoT

Use this API to define a Custom Metric published by your devices to Device Defender.

Requires permission to access the CreateCustomMetric action.

Request Syntax
POST /custom-metric/metricName HTTP/1.1
Content-type: application/json

{
"clientRequestToken": "string",
"displayName": "string",
"metricType": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 64)

The name of the custom metric. This will be used in the metric report submitted from the device/
thing. Shouldn't begin with aws:. Cannot be updated once defined.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

clientRequestToken (p. 64)

Each custom metric must have a unique client request token. If you try to create a new custom
metric that already exists with a different token, an exception occurs. If you omit this value, AWS
SDKs will automatically generate a unique client request.

Type: String

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

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

Required: Yes

64
 AWS IoT API Reference
CreateCustomMetric

displayName (p. 64)

Field represents a friendly name in the console for the custom metric; it doesn't have to be unique.
Don't use this name as the metric identifier in the device metric report. Can be updated once
defined.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Graph}\x20]*

Required: No
metricType (p. 64)

The type of the custom metric. Types include string-list, ip-address-list, number-list,
and number.

Type: String

Valid Values: string-list | ip-address-list | number-list | number

Required: Yes
tags (p. 64)

Metadata that can be used to manage the custom metric.

Type: Array of Tag (p. 979) objects

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"metricArn": "string",
"metricName": "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.

metricArn (p. 65)

The Amazon Resource Number (ARN) of the custom metric, e.g. arn:aws-
partition:iot:region:accountId:custommetric/metricName

Type: String
metricName (p. 65)

The name of the custom metric to be used in the metric report.

Type: String

65
 AWS IoT API Reference
CreateCustomMetric

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

66
 AWS IoT API Reference
CreateDimension

CreateDimension
Service: AWS IoT

Create a dimension that you can use to limit the scope of a metric used in a security profile for AWS IoT
Device Defender. For example, using a TOPIC_FILTER dimension, you can narrow down the scope of the
metric only to MQTT topics whose name match the pattern specified in the dimension.

Requires permission to access the CreateDimension action.

Request Syntax
POST /dimensions/name HTTP/1.1
Content-type: application/json

{
"clientRequestToken": "string",
"stringValues": [ "string" ],
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"type": "string"
}

URI Request Parameters

The request uses the following URI parameters.

name (p. 67)

A unique identifier for the dimension. Choose something that describes the type and value to make
it easy to remember what it does.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

clientRequestToken (p. 67)

Each dimension must have a unique client request token. If you try to create a new dimension with
the same token as a dimension that already exists, an exception occurs. If you omit this value, AWS
SDKs will automatically generate a unique client request.

Type: String

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

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

Required: Yes

67
 AWS IoT API Reference
CreateDimension

stringValues (p. 67)

Specifies the value or list of values for the dimension. For TOPIC_FILTER dimensions, this is a
pattern used to match the MQTT topic (for example, "admin/#").

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

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

Required: Yes
tags (p. 67)

Metadata that can be used to manage the dimension.

Type: Array of Tag (p. 979) objects

Required: No
type (p. 67)

Specifies the type of dimension. Supported types: TOPIC_FILTER.

Type: String

Valid Values: TOPIC_FILTER

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"arn": "string",
"name": "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.

arn (p. 68)

The Amazon Resource Name (ARN) of the created dimension.

Type: String
name (p. 68)

A unique identifier for the dimension.

Type: String

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

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

68
 AWS IoT API Reference
CreateDimension

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

69
 AWS IoT API Reference
CreateDomainConfiguration

CreateDomainConfiguration
Service: AWS IoT

Creates a domain configuration.

Requires permission to access the CreateDomainConfiguration action.

Request Syntax
POST /domainConfigurations/domainConfigurationName HTTP/1.1
Content-type: application/json

{
"authorizerConfig": {
"allowAuthorizerOverride": boolean,
"defaultAuthorizerName": "string"
},
"domainName": "string",
"serverCertificateArns": [ "string" ],
"serviceType": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"validationCertificateArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 70)

The name of the domain configuration. This value must be unique to a region.

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

Pattern: [\w.-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

authorizerConfig (p. 70)

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 812) object

Required: No
domainName (p. 70)

The name of the domain.

Type: String

70
 AWS IoT API Reference
CreateDomainConfiguration

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

Required: No
serverCertificateArns (p. 70)

The ARNs of the certificates that AWS IoT passes to the device during the TLS handshake. Currently
you can specify only one certificate ARN. This value is not required for AWS-managed domains.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 1 item.

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

Pattern: arn:aws(-cn|-us-gov|-iso-b|-iso)?:acm:[a-z]{2}-(gov-|iso-|isob-)?[a-
z]{4,9}-\d{1}:\d{12}:certificate/[a-zA-Z0-9/-]+

Required: No
serviceType (p. 70)

The type of service delivered by the endpoint.

Note
AWS IoT Core currently supports only the DATA service type.

Type: String

Valid Values: DATA | CREDENTIAL_PROVIDER | JOBS

Required: No
tags (p. 70)

Metadata which can be used to manage the domain configuration.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...
For the CLI command-line parameter use format: &&tags "key1=value1&key2=value2..."
For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Type: Array of Tag (p. 979) objects

Required: No
validationCertificateArn (p. 70)

The certificate used to validate the server certificate and prove domain name ownership. This
certificate must be signed by a public certificate authority. This value is not required for AWS-
managed domains.

Type: String

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

Pattern: arn:aws(-cn|-us-gov|-iso-b|-iso)?:acm:[a-z]{2}-(gov-|iso-|isob-)?[a-
z]{4,9}-\d{1}:\d{12}:certificate/[a-zA-Z0-9/-]+

Required: No

Response Syntax
HTTP/1.1 200

71
 AWS IoT API Reference
CreateDomainConfiguration

Content-type: application/json

{
"domainConfigurationArn": "string",
"domainConfigurationName": "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.

domainConfigurationArn (p. 71)

The ARN of the domain configuration.

Type: String
domainConfigurationName (p. 71)

The name of the domain configuration.

Type: String

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

Pattern: [\w.-]+

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

72
 AWS IoT API Reference
CreateDomainConfiguration

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

73
 AWS IoT API Reference
CreateDynamicThingGroup

CreateDynamicThingGroup
Service: AWS IoT

Creates a dynamic thing group.

Requires permission to access the CreateDynamicThingGroup action.

Request Syntax
POST /dynamic-thing-groups/thingGroupName HTTP/1.1
Content-type: application/json

{
"indexName": "string",
"queryString": "string",
"queryVersion": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"thingGroupProperties": {
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean
},
"thingGroupDescription": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

thingGroupName (p. 74)

The dynamic thing group name to create.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

indexName (p. 74)

The dynamic thing group index name.

Note
Currently one index is supported: AWS_Things.

Type: String

74
 AWS IoT API Reference
CreateDynamicThingGroup

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

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

Required: No
queryString (p. 74)

The dynamic thing group search query string.

See Query Syntax for information about query string syntax.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 74)

The dynamic thing group query version.

Note
Currently one query version is supported: "2017-09-30". If not specified, the query version
defaults to this value.

Type: String

Required: No
tags (p. 74)

Metadata which can be used to manage the dynamic thing group.

Type: Array of Tag (p. 979) objects

Required: No
thingGroupProperties (p. 74)

The dynamic thing group properties.

Type: ThingGroupProperties (p. 993) object

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"indexName": "string",
"queryString": "string",
"queryVersion": "string",
"thingGroupArn": "string",
"thingGroupId": "string",
"thingGroupName": "string"
}

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

75
 AWS IoT API Reference
CreateDynamicThingGroup

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

indexName (p. 75)

The dynamic thing group index name.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
queryString (p. 75)

The dynamic thing group search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 75)

The dynamic thing group query version.

Type: String
thingGroupArn (p. 75)

The dynamic thing group ARN.

Type: String
thingGroupId (p. 75)

The dynamic thing group ID.

Type: String

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

Pattern: [a-zA-Z0-9\-]+
thingGroupName (p. 75)

The dynamic thing group name.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

76
 AWS IoT API Reference
CreateDynamicThingGroup

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

77
 AWS IoT API Reference
CreateFleetMetric

CreateFleetMetric
Service: AWS IoT

Creates a fleet metric.

Requires permission to access the CreateFleetMetric action.

Request Syntax
PUT /fleet-metric/metricName HTTP/1.1
Content-type: application/json

{
"aggregationField": "string",
"aggregationType": {
"name": "string",
"values": [ "string" ]
},
"description": "string",
"indexName": "string",
"period": number,
"queryString": "string",
"queryVersion": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"unit": "string"
}

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 78)

The name of the fleet metric to create.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

aggregationField (p. 78)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

78
 AWS IoT API Reference
CreateFleetMetric

aggregationType (p. 78)

The type of the aggregation query.

Type: AggregationType (p. 791) object

Required: Yes
description (p. 78)

The fleet metric description.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [\p{Graph}\x20]*

Required: No
indexName (p. 78)

The name of the index to search.

Type: String

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

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

Required: No
period (p. 78)

The time in seconds between fleet metric emissions. Range [60(1 min), 86400(1 day)] and must be
multiple of 60.

Type: Integer

Valid Range: Minimum value of 60. Maximum value of 86400.

Required: Yes
queryString (p. 78)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 78)

The query version.

Type: String

Required: No
tags (p. 78)

Metadata, which can be used to manage the fleet metric.

Type: Array of Tag (p. 979) objects

79
 AWS IoT API Reference
CreateFleetMetric

Required: No
unit (p. 78)

Used to support unit transformation such as milliseconds to seconds. The unit must be supported by
CW metric. Default to null.

Type: String

Valid Values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes |

Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits
| Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/
Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second
| Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"metricArn": "string",
"metricName": "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.

metricArn (p. 80)

The Amazon Resource Name (ARN) of the new fleet metric.

Type: String
metricName (p. 80)

The name of the fleet metric to create.

Type: String

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

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

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

80
 AWS IoT API Reference
CreateFleetMetric

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2

81
 AWS IoT API Reference
CreateFleetMetric

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

82
 AWS IoT API Reference
CreateJob

CreateJob
Service: AWS IoT

Creates a job.

Requires permission to access the CreateJob action.

Request Syntax
PUT /jobs/jobId HTTP/1.1
Content-type: application/json

{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"description": "string",
"document": "string",
"documentSource": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobTemplateArn": "string",
"namespaceId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"targets": [ "string" ],
"targetSelection": "string",
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

URI Request Parameters

The request uses the following URI parameters.

83
 AWS IoT API Reference
CreateJob

jobId (p. 83)

A job identifier which must be unique for your AWS account. We recommend using a UUID. Alpha-
numeric characters, "-" and "_" are valid for use here.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

abortConfig (p. 83)

Allows you to create criteria to abort a job.

Type: AbortConfig (p. 782) object

Required: No
description (p. 83)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
document (p. 83)

The job document. Required if you don't specify a value for documentSource.

Type: String

Length Constraints: Maximum length of 32768.

Required: No
documentSource (p. 83)

An S3 link to the job document. Required if you don't specify a value for document.
Note
If the job document resides in an S3 bucket, you must use a placeholder link when
specifying the document.
The placeholder link is of the following form:
${aws:iot:s3-presigned-url:https://s3.amazonaws.com/bucket/key}
where bucket is your bucket name and key is the object in the bucket to which you are
linking.

Type: String

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

Required: No

84
 AWS IoT API Reference
CreateJob

jobExecutionsRolloutConfig (p. 83)

Allows you to create a staged rollout of the job.

Type: JobExecutionsRolloutConfig (p. 895) object

Required: No
jobTemplateArn (p. 83)

The ARN of the job template used to create the job.

Type: String

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

Pattern: ^arn:[!-~]+$

Required: No
namespaceId (p. 83)

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 notifications 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.

Type: String

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

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

Required: No
presignedUrlConfig (p. 83)

Configuration information for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 937) object

Required: No
tags (p. 83)

Metadata which can be used to manage the job.

Type: Array of Tag (p. 979) objects

Required: No
targets (p. 83)

A list of things and thing groups to which the job should be sent.

Type: Array of strings

Array Members: Minimum number of 1 item.

Length Constraints: Maximum length of 2048.

85
 AWS IoT API Reference
CreateJob

Required: Yes
targetSelection (p. 83)

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those
things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be
run on a thing when a change is detected in a target. For example, a job will run on a thing when
the thing is added to a target group, even after the job was completed by all things originally in the
group.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No
timeoutConfig (p. 83)

Specifies the amount of time each device has to finish its execution of the job. The timer is started
when the job execution status is set to IN_PROGRESS. If the job execution status is not set to
another terminal state before the time expires, it will be automatically set to TIMED_OUT.

Type: TimeoutConfig (p. 999) object

Required: No

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. 86)

The job description.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
jobArn (p. 86)

The job ARN.

Type: String
jobId (p. 86)

The unique identifier you assigned to this job.

86
 AWS IoT API Reference
CreateJob

Type: String

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

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

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

87
 AWS IoT API Reference
CreateJobTemplate

CreateJobTemplate
Service: AWS IoT

Creates a job template.

Requires permission to access the CreateJobTemplate action.

Request Syntax
PUT /job-templates/jobTemplateId HTTP/1.1
Content-type: application/json

{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"description": "string",
"document": "string",
"documentSource": "string",
"jobArn": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

URI Request Parameters

The request uses the following URI parameters.

jobTemplateId (p. 88)

A unique identifier for the job template. We recommend using a UUID. Alpha-numeric characters, "-",
and "_" are valid for use here.

88
 AWS IoT API Reference
CreateJobTemplate

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

abortConfig (p. 88)

The criteria that determine when and how a job abort takes place.

Type: AbortConfig (p. 782) object

Required: No
description (p. 88)

A description of the job document.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: Yes
document (p. 88)

The job document. Required if you don't specify a value for documentSource.

Type: String

Length Constraints: Maximum length of 32768.

Required: No
documentSource (p. 88)

An S3 link to the job document to use in the template. Required if you don't specify a value for
document.
Note
If the job document resides in an S3 bucket, you must use a placeholder link when
specifying the document.
The placeholder link is of the following form:
${aws:iot:s3-presigned-url:https://s3.amazonaws.com/bucket/key}
where bucket is your bucket name and key is the object in the bucket to which you are
linking.

Type: String

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

Required: No
jobArn (p. 88)

The ARN of the job to use as the basis for the job template.

Type: String

89
 AWS IoT API Reference
CreateJobTemplate

Required: No
jobExecutionsRolloutConfig (p. 88)

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 895) object

Required: No
presignedUrlConfig (p. 88)

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 937) object

Required: No
tags (p. 88)

Metadata that can be used to manage the job template.

Type: Array of Tag (p. 979) objects

Required: No
timeoutConfig (p. 88)

Specifies the amount of time each device has to finish its execution of the job. A timer is started
when the job execution status is set to IN_PROGRESS. If the job execution status is not set to
another terminal state before the timer expires, it will be automatically set to TIMED_OUT.

Type: TimeoutConfig (p. 999) object

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"jobTemplateArn": "string",
"jobTemplateId": "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.

jobTemplateArn (p. 90)

The ARN of the job template.

Type: String

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

Pattern: ^arn:[!-~]+$

90
 AWS IoT API Reference
CreateJobTemplate

jobTemplateId (p. 90)

The unique identifier of the job template.

Type: String

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

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

Errors
ConflictException

A resource with the same name already exists.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

91
 AWS IoT API Reference
CreateJobTemplate

• AWS SDK for Ruby V3

92
 AWS IoT API Reference
CreateKeysAndCertificate

CreateKeysAndCertificate
Service: AWS IoT

Creates a 2048-bit RSA key pair and issues an X.509 certificate using the issued public key. You can also
call CreateKeysAndCertificate over MQTT from a device, for more information, see Provisioning
MQTT API.

Note This is the only time AWS IoT issues the private key for this certificate, so it is important to keep it
in a secure location.

Requires permission to access the CreateKeysAndCertificate action.

Request Syntax
POST /keys-and-certificate?setAsActive=setAsActive HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

setAsActive (p. 93)

Specifies whether the certificate is active.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateArn": "string",
"certificateId": "string",
"certificatePem": "string",
"keyPair": {
"PrivateKey": "string",
"PublicKey": "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.

certificateArn (p. 93)

The ARN of the certificate.

Type: String

93
 AWS IoT API Reference
CreateKeysAndCertificate

certificateId (p. 93)

The ID of the certificate. AWS IoT issues a default subject name for the certificate (for example, AWS
IoT Certificate).

Type: String

Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+
certificatePem (p. 93)

The certificate data, in PEM format.

Type: String

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

keyPair (p. 93)

The generated key pair.

Type: KeyPair (p. 908) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

94
 AWS IoT API Reference
CreateKeysAndCertificate

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

95
 AWS IoT API Reference
CreateMitigationAction

CreateMitigationAction
Service: AWS IoT

Defines an action that can be applied to audit findings by using StartAuditMitigationActionsTask. Only
certain types of mitigation actions can be applied to specific check names. For more information, see
Mitigation actions. Each mitigation action can apply only one type of change.

Requires permission to access the CreateMitigationAction action.

Request Syntax
POST /mitigationactions/actions/actionName HTTP/1.1
Content-type: application/json

{
"actionParams": {
"addThingsToThingGroupParams": {
"overrideDynamicGroups": boolean,
"thingGroupNames": [ "string" ]
},
"enableIoTLoggingParams": {
"logLevel": "string",
"roleArnForLogging": "string"
},
"publishFindingToSnsParams": {
"topicArn": "string"
},
"replaceDefaultPolicyVersionParams": {
"templateName": "string"
},
"updateCACertificateParams": {
"action": "string"
},
"updateDeviceCertificateParams": {
"action": "string"
}
},
"roleArn": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

actionName (p. 96)

A friendly name for the action. Choose a friendly name that accurately describes the action (for
example, EnableLoggingAction).

Length Constraints: Maximum length of 128.

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

Required: Yes

96
 AWS IoT API Reference
CreateMitigationAction

Request Body
The request accepts the following data in JSON format.

actionParams (p. 96)

Defines the type of action and the parameters for that action.

Type: MitigationActionParams (p. 921) object

Required: Yes
roleArn (p. 96)

The ARN of the IAM role that is used to apply the mitigation action.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
tags (p. 96)

Metadata that can be used to manage the mitigation action.

Type: Array of Tag (p. 979) objects

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"actionArn": "string",
"actionId": "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.

actionArn (p. 97)

The ARN for the new mitigation action.

Type: String
actionId (p. 97)

A unique identifier for the new mitigation action.

Type: String

97
 AWS IoT API Reference
CreateMitigationAction

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

98
 AWS IoT API Reference
CreateOTAUpdate

CreateOTAUpdate
Service: AWS IoT

Creates an AWS IoT OTA update on a target group of things or groups.

Requires permission to access the CreateOTAUpdate action.

Request Syntax
POST /otaUpdates/otaUpdateId HTTP/1.1
Content-type: application/json

{
"additionalParameters": {
"string" : "string"
},
"awsJobAbortConfig": {
"abortCriteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"awsJobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"awsJobPresignedUrlConfig": {
"expiresInSec": number
},
"awsJobTimeoutConfig": {
"inProgressTimeoutInMinutes": number
},
"description": "string",
"files": [
{
"attributes": {
"string" : "string"
},
"codeSigning": {
"awsSignerJobId": "string",
"customCodeSigning": {
"certificateChain": {
"certificateName": "string",
"inlineDocument": "string"
},
"hashAlgorithm": "string",
"signature": {
"inlineDocument": blob
},
"signatureAlgorithm": "string"
},
"startSigningJobParameter": {

99
 AWS IoT API Reference
CreateOTAUpdate

"destination": {
"s3Destination": {
"bucket": "string",
"prefix": "string"
}
},
"signingProfileName": "string",
"signingProfileParameter": {
"certificateArn": "string",
"certificatePathOnDevice": "string",
"platform": "string"
}
}
},
"fileLocation": {
"s3Location": {
"bucket": "string",
"key": "string",
"version": "string"
},
"stream": {
"fileId": number,
"streamId": "string"
}
},
"fileName": "string",
"fileType": number,
"fileVersion": "string"
}
],
"protocols": [ "string" ],
"roleArn": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"targets": [ "string" ],
"targetSelection": "string"
}

URI Request Parameters

The request uses the following URI parameters.

otaUpdateId (p. 99)

The ID of the OTA update to be created.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

additionalParameters (p. 99)

A list of additional OTA update parameters which are name-value pairs.

100
 AWS IoT API Reference
CreateOTAUpdate

Type: String to string map

Required: No
awsJobAbortConfig (p. 99)

The criteria that determine when and how a job abort takes place.

Type: AwsJobAbortConfig (p. 817) object

Required: No
awsJobExecutionsRolloutConfig (p. 99)

Configuration for the rollout of OTA updates.

Type: AwsJobExecutionsRolloutConfig (p. 820) object

Required: No
awsJobPresignedUrlConfig (p. 99)

Configuration information for pre-signed URLs.

Type: AwsJobPresignedUrlConfig (p. 822) object

Required: No
awsJobTimeoutConfig (p. 99)

Specifies the amount of time each device has to finish its execution of the job. A timer is started
when the job execution status is set to IN_PROGRESS. If the job execution status is not set to
another terminal state before the timer expires, it will be automatically set to TIMED_OUT.

Type: AwsJobTimeoutConfig (p. 824) object

Required: No
description (p. 99)

The description of the OTA update.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 99)

The files to be streamed by the OTA update.

Type: Array of OTAUpdateFile (p. 925) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: Yes
protocols (p. 99)

The protocol used to transfer the OTA update image. Valid values are [HTTP], [MQTT], [HTTP,
MQTT]. When both HTTP and MQTT are specified, the target device can choose the protocol.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 2 items.

101
 AWS IoT API Reference
CreateOTAUpdate

Valid Values: MQTT | HTTP

Required: No
roleArn (p. 99)

The IAM role that grants AWS IoT Core access to the Amazon S3, AWS IoT jobs and AWS Code
Signing resources to create an OTA update job.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
tags (p. 99)

Metadata which can be used to manage updates.

Type: Array of Tag (p. 979) objects

Required: No
targets (p. 99)

The devices targeted to receive OTA updates.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: Yes
targetSelection (p. 99)

Specifies whether the update will continue to run (CONTINUOUS), or will be complete after all the
things specified as targets have completed the update (SNAPSHOT). If continuous, the update may
also be run on a thing when a change is detected in a target. For example, an update will run on a
thing when the thing is added to a target group, even after the update was completed by all things
originally in the group. Valid values: CONTINUOUS | SNAPSHOT.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"awsIotJobArn": "string",
"awsIotJobId": "string",
"otaUpdateArn": "string",
"otaUpdateId": "string",
"otaUpdateStatus": "string"
}

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

102
 AWS IoT API Reference
CreateOTAUpdate

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

awsIotJobArn (p. 102)

The AWS IoT job ARN associated with the OTA update.

Type: String
awsIotJobId (p. 102)

The AWS IoT job ID associated with the OTA update.

Type: String
otaUpdateArn (p. 102)

The OTA update ARN.

Type: String
otaUpdateId (p. 102)

The OTA update ID.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
otaUpdateStatus (p. 102)

The OTA update status.

Type: String

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

103
 AWS IoT API Reference
CreateOTAUpdate

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

104
 AWS IoT API Reference
CreatePolicy

CreatePolicy
Service: AWS IoT

Creates an AWS IoT policy.

The created policy is the default version for the policy. This operation creates a policy version with a
version identifier of 1 and sets 1 as the policy's default version.

Requires permission to access the CreatePolicy action.

Request Syntax
POST /policies/policyName HTTP/1.1
Content-type: application/json

{
"policyDocument": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 105)

The policy name.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

policyDocument (p. 105)

The JSON document that describes the policy. policyDocument must have a minimum length of 1,
with a maximum length of 2048, excluding whitespace.

Type: String

Required: Yes
tags (p. 105)

Metadata which can be used to manage the policy.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...

105
 AWS IoT API Reference
CreatePolicy

For the CLI command-line parameter use format: &&tags "key1=value1&key2=value2..."

For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Type: Array of Tag (p. 979) objects

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"policyArn": "string",
"policyDocument": "string",
"policyName": "string",
"policyVersionId": "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.

policyArn (p. 106)

The policy ARN.

Type: String
policyDocument (p. 106)

The JSON document that describes the policy.

Type: String
policyName (p. 106)

The policy name.

Type: String

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

Pattern: [\w+=,.@-]+
policyVersionId (p. 106)

The policy version ID.

Type: String

Pattern: [0-9]+

Errors
InternalFailureException

An unexpected error has occurred.

106
 AWS IoT API Reference
CreatePolicy

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MalformedPolicyException

The policy documentation is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

107
 AWS IoT API Reference
CreatePolicyVersion

CreatePolicyVersion
Service: AWS IoT

Creates a new version of the specified AWS IoT policy. To update a policy, create a new policy
version. A managed policy can have up to five versions. If the policy has five versions, you must use
DeletePolicyVersion (p. 191) to delete an existing version before you create a new one.

Optionally, you can set the new version as the policy's default version. The default version is the
operative version (that is, the version that is in effect for the certificates to which the policy is attached).

Requires permission to access the CreatePolicyVersion action.

Request Syntax
POST /policies/policyName/version?setAsDefault=setAsDefault HTTP/1.1
Content-type: application/json

{
"policyDocument": "string"
}

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 108)

The policy name.

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

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

Required: Yes
setAsDefault (p. 108)

Specifies whether the policy version is set as the default. When this parameter is true, the new policy
version becomes the operative version (that is, the version that is in effect for the certificates to
which the policy is attached).

Request Body
The request accepts the following data in JSON format.

policyDocument (p. 108)

The JSON document that describes the policy. Minimum length of 1. Maximum length of 2048,
excluding whitespace.

Type: String

Required: Yes

Response Syntax
HTTP/1.1 200

108
 AWS IoT API Reference
CreatePolicyVersion

Content-type: application/json

{
"isDefaultVersion": boolean,
"policyArn": "string",
"policyDocument": "string",
"policyVersionId": "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.

isDefaultVersion (p. 108)

Specifies whether the policy version is the default.

Type: Boolean
policyArn (p. 108)

The policy ARN.

Type: String
policyDocument (p. 108)

The JSON document that describes the policy.

Type: String
policyVersionId (p. 108)

The policy version ID.

Type: String

Pattern: [0-9]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MalformedPolicyException

The policy documentation is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

109
 AWS IoT API Reference
CreatePolicyVersion

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionsLimitExceededException

The number of policy versions exceeds the limit.

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

110
 AWS IoT API Reference
CreateProvisioningClaim

CreateProvisioningClaim
Service: AWS IoT

Creates a provisioning claim.

Requires permission to access the CreateProvisioningClaim action.

Request Syntax
POST /provisioning-templates/templateName/provisioning-claim HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 111)

The name of the provisioning template to use.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateId": "string",
"certificatePem": "string",
"expiration": number,
"keyPair": {
"PrivateKey": "string",
"PublicKey": "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.

certificateId (p. 111)

The ID of the certificate.

Type: String

111
 AWS IoT API Reference
CreateProvisioningClaim

Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+
certificatePem (p. 111)

The provisioning claim certificate.

Type: String

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

expiration (p. 111)

The provisioning claim expiration time.

Type: Timestamp
keyPair (p. 111)

The provisioning claim key pair.

Type: KeyPair (p. 908) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

112
 AWS IoT API Reference
CreateProvisioningClaim

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

113
 AWS IoT API Reference
CreateProvisioningTemplate

CreateProvisioningTemplate
Service: AWS IoT

Creates a fleet provisioning template.

Requires permission to access the CreateProvisioningTemplate action.

Request Syntax
POST /provisioning-templates HTTP/1.1
Content-type: application/json

{
"description": "string",
"enabled": boolean,
"preProvisioningHook": {
"payloadVersion": "string",
"targetArn": "string"
},
"provisioningRoleArn": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"templateBody": "string",
"templateName": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

description (p. 114)

The description of the fleet provisioning template.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: [^\p{C}]*

Required: No
enabled (p. 114)

True to enable the fleet provisioning template, otherwise false.

Type: Boolean

Required: No
preProvisioningHook (p. 114)

Creates a pre-provisioning hook template.

114
 AWS IoT API Reference
CreateProvisioningTemplate

Type: ProvisioningHook (p. 938) object

Required: No
provisioningRoleArn (p. 114)

The role ARN for the role associated with the fleet provisioning template. This IoT role grants
permission to provision a device.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
tags (p. 114)

Metadata which can be used to manage the fleet provisioning template.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...
For the CLI command-line parameter use format: &&tags "key1=value1&key2=value2..."
For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Type: Array of Tag (p. 979) objects

Required: No
templateBody (p. 114)

The JSON formatted contents of the fleet provisioning template.

Type: String

Required: Yes
templateName (p. 114)

The name of the fleet provisioning template.

Type: String

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"defaultVersionId": number,
"templateArn": "string",
"templateName": "string"
}

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

115
 AWS IoT API Reference
CreateProvisioningTemplate

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

defaultVersionId (p. 115)

The default version of the fleet provisioning template.

Type: Integer
templateArn (p. 115)

The ARN that identifies the provisioning template.

Type: String
templateName (p. 115)

The name of the fleet provisioning template.

Type: String

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

Pattern: ^[0-9A-Za-z_-]+$

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

116
 AWS IoT API Reference
CreateProvisioningTemplate

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

117
 AWS IoT API Reference
CreateProvisioningTemplateVersion

CreateProvisioningTemplateVersion
Service: AWS IoT

Creates a new version of a fleet provisioning template.

Requires permission to access the CreateProvisioningTemplateVersion action.

Request Syntax
POST /provisioning-templates/templateName/versions?setAsDefault=setAsDefault HTTP/1.1
Content-type: application/json

{
"templateBody": "string"
}

URI Request Parameters

The request uses the following URI parameters.

setAsDefault (p. 118)

Sets a fleet provision template version as the default version.

templateName (p. 118)

The name of the fleet provisioning template.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

Request Body
The request accepts the following data in JSON format.

templateBody (p. 118)

The JSON formatted contents of the fleet provisioning template.

Type: String

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"isDefaultVersion": boolean,
"templateArn": "string",
"templateName": "string",
"versionId": number

118
 AWS IoT API Reference
CreateProvisioningTemplateVersion

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.

isDefaultVersion (p. 118)

True if the fleet provisioning template version is the default version, otherwise false.

Type: Boolean
templateArn (p. 118)

The ARN that identifies the provisioning template.

Type: String
templateName (p. 118)

The name of the fleet provisioning template.

Type: String

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

Pattern: ^[0-9A-Za-z_-]+$
versionId (p. 118)

The version of the fleet provisioning template.

Type: Integer

Errors
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

119
 AWS IoT API Reference
CreateProvisioningTemplateVersion

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionsLimitExceededException

The number of policy versions exceeds the limit.

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

120
 AWS IoT API Reference
CreateRoleAlias

CreateRoleAlias
Service: AWS IoT

Creates a role alias.

Requires permission to access the CreateRoleAlias action.

Request Syntax
POST /role-aliases/roleAlias HTTP/1.1
Content-type: application/json

{
"credentialDurationSeconds": number,
"roleArn": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

roleAlias (p. 121)

The role alias that points to a role ARN. This allows you to change the role without having to update
the device.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

credentialDurationSeconds (p. 121)

How long (in seconds) the credentials will be valid. The default value is 3,600 seconds.

Type: Integer

Valid Range: Minimum value of 900. Maximum value of 43200.

Required: No
roleArn (p. 121)

The role ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

121
 AWS IoT API Reference
CreateRoleAlias

Required: Yes
tags (p. 121)

Metadata which can be used to manage the role alias.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...
For the CLI command-line parameter use format: &&tags "key1=value1&key2=value2..."
For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Type: Array of Tag (p. 979) objects

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"roleAlias": "string",
"roleAliasArn": "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.

roleAlias (p. 122)

The role alias.

Type: String

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

Pattern: [\w=,@-]+
roleAliasArn (p. 122)

The role alias ARN.

Type: String

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

122
 AWS IoT API Reference
CreateRoleAlias

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

123
 AWS IoT API Reference
CreateScheduledAudit

CreateScheduledAudit
Service: AWS IoT

Creates a scheduled audit that is run at a specified time interval.

Requires permission to access the CreateScheduledAudit action.

Request Syntax
POST /audit/scheduledaudits/scheduledAuditName HTTP/1.1
Content-type: application/json

{
"dayOfMonth": "string",
"dayOfWeek": "string",
"frequency": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"targetCheckNames": [ "string" ]
}

URI Request Parameters

The request uses the following URI parameters.

scheduledAuditName (p. 124)

The name you want to give to the scheduled audit. (Max. 128 chars)

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

dayOfMonth (p. 124)

The day of the month on which the scheduled audit takes place. This can be "1" through "31" or
"LAST". This field is required if the "frequency" parameter is set to MONTHLY. If days 29 to 31 are
specified, and the month doesn't have that many days, the audit takes place on the LAST day of the
month.

Type: String

Pattern: ^([1-9]|[12][0-9]|3[01])$|^LAST$

Required: No
dayOfWeek (p. 124)

The day of the week on which the scheduled audit takes place, either SUN, MON, TUE, WED, THU, FRI,
or SAT. This field is required if the frequency parameter is set to WEEKLY or BIWEEKLY.

124
 AWS IoT API Reference
CreateScheduledAudit

Type: String

Valid Values: SUN | MON | TUE | WED | THU | FRI | SAT

Required: No
frequency (p. 124)

How often the scheduled audit takes place, either DAILY, WEEKLY, BIWEEKLY or MONTHLY. The start
time of each audit is determined by the system.

Type: String

Valid Values: DAILY | WEEKLY | BIWEEKLY | MONTHLY

Required: Yes
tags (p. 124)

Metadata that can be used to manage the scheduled audit.

Type: Array of Tag (p. 979) objects

Required: No
targetCheckNames (p. 124)

Which checks are performed during the scheduled audit. Checks must be enabled for your account.
(Use DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: Array of strings

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"scheduledAuditArn": "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.

scheduledAuditArn (p. 125)

The ARN of the scheduled audit.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

125
 AWS IoT API Reference
CreateScheduledAudit

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

126
 AWS IoT API Reference
CreateSecurityProfile

CreateSecurityProfile
Service: AWS IoT

Creates a Device Defender security profile.

Requires permission to access the CreateSecurityProfile action.

Request Syntax
POST /security-profiles/securityProfileName HTTP/1.1
Content-type: application/json

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"securityProfileDescription": "string",
"tags": [
{

127
 AWS IoT API Reference
CreateSecurityProfile

"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

securityProfileName (p. 127)

The name you are giving to the security profile.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

additionalMetricsToRetain (p. 127)

This parameter has been deprecated.

Please use CreateSecurityProfile:additionalMetricsToRetainV2 (p. 128) instead.

A list of metrics whose data is retained (stored). By default, data is retained for any metric used
in the profile's behaviors, but it is also retained for any metric specified here. Can be used with
custom metrics; cannot be used with dimensions.

Type: Array of strings

Required: No
additionalMetricsToRetainV2 (p. 127)

A list of metrics whose data is retained (stored). By default, data is retained for any metric used
in the profile's behaviors, but it is also retained for any metric specified here. Can be used with
custom metrics; cannot be used with dimensions.

Type: Array of MetricToRetain (p. 916) objects

Required: No
alertTargets (p. 127)

Specifies the destinations to which alerts are sent. (Alerts are always sent to the console.) Alerts are
generated when a device (thing) violates a behavior.

Type: String to AlertTarget (p. 792) object map

Valid Keys: SNS

Required: No
behaviors (p. 127)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 825) objects

128
 AWS IoT API Reference
CreateSecurityProfile

Array Members: Maximum number of 100 items.

Required: No
securityProfileDescription (p. 127)

A description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No
tags (p. 127)

Metadata that can be used to manage the security profile.

Type: Array of Tag (p. 979) objects

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"securityProfileArn": "string",
"securityProfileName": "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.

securityProfileArn (p. 129)

The ARN of the security profile.

Type: String
securityProfileName (p. 129)

The name you gave to the security profile.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

129
 AWS IoT API Reference
CreateSecurityProfile

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

130
 AWS IoT API Reference
CreateStream

CreateStream
Service: AWS IoT

Creates a stream for delivering one or more large files in chunks over MQTT. A stream transports data
bytes in chunks or blocks packaged as MQTT messages from a source like S3. You can have one or more
files associated with a stream.

Requires permission to access the CreateStream action.

Request Syntax
POST /streams/streamId HTTP/1.1
Content-type: application/json

{
"description": "string",
"files": [
{
"fileId": number,
"s3Location": {
"bucket": "string",
"key": "string",
"version": "string"
}
}
],
"roleArn": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

streamId (p. 131)

The stream ID.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

description (p. 131)

A description of the stream.

Type: String

131
 AWS IoT API Reference
CreateStream

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 131)

The files to stream.

Type: Array of StreamFile (p. 975) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: Yes
roleArn (p. 131)

An IAM role that allows the IoT service principal assumes to access your S3 files.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
tags (p. 131)

Metadata which can be used to manage streams.

Type: Array of Tag (p. 979) objects

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"description": "string",
"streamArn": "string",
"streamId": "string",
"streamVersion": number
}

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. 132)

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

132
 AWS IoT API Reference
CreateStream

streamArn (p. 132)

The stream ARN.

Type: String
streamId (p. 132)

The stream ID.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
streamVersion (p. 132)

The version of the stream.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 65535.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

133
 AWS IoT API Reference
CreateStream

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

134
 AWS IoT API Reference
CreateThing

CreateThing
Service: AWS IoT

Creates a thing record in the registry. If this call is made multiple times using the same thing name
and configuration, the call will succeed. If this call is made with the same thing name but different
configuration a ResourceAlreadyExistsException is thrown.
Note
This is a control plane operation. See Authorization for information about authorizing control
plane actions.

Requires permission to access the CreateThing action.

Request Syntax
POST /things/thingName HTTP/1.1
Content-type: application/json

{
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean
},
"billingGroupName": "string",
"thingTypeName": "string"
}

URI Request Parameters

The request uses the following URI parameters.

thingName (p. 135)

The name of the thing to create.

You can't change a thing's name after you create it. To change a thing's name, you must create a new
thing, give it the new name, and then delete the old thing.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

attributePayload (p. 135)

The attribute payload, which consists of up to three name/value pairs in a JSON document. For
example:

{\"attributes\":{\"string1\":\"string2\"}}

Type: AttributePayload (p. 797) object

135
 AWS IoT API Reference
CreateThing

Required: No
billingGroupName (p. 135)

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

Type: String

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

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

Required: No
thingTypeName (p. 135)

The name of the thing type associated with the new thing.

Type: String

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

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

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"thingArn": "string",
"thingId": "string",
"thingName": "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.

thingArn (p. 136)

The ARN of the new thing.

Type: String
thingId (p. 136)

The thing ID.

Type: String
thingName (p. 136)

The name of the new thing.

Type: String

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

136
 AWS IoT API Reference
CreateThing

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

137
 AWS IoT API Reference
CreateThingGroup

CreateThingGroup
Service: AWS IoT

Create a thing group.

Note
This is a control plane operation. See Authorization for information about authorizing control
plane actions.

Requires permission to access the CreateThingGroup action.

Request Syntax
POST /thing-groups/thingGroupName HTTP/1.1
Content-type: application/json

{
"parentGroupName": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"thingGroupProperties": {
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean
},
"thingGroupDescription": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

thingGroupName (p. 138)

The thing group name to create.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

parentGroupName (p. 138)

The name of the parent thing group.

Type: String

138
 AWS IoT API Reference
CreateThingGroup

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

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

Required: No
tags (p. 138)

Metadata which can be used to manage the thing group.

Type: Array of Tag (p. 979) objects

Required: No
thingGroupProperties (p. 138)

The thing group properties.

Type: ThingGroupProperties (p. 993) object

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"thingGroupArn": "string",
"thingGroupId": "string",
"thingGroupName": "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.

thingGroupArn (p. 139)

The thing group ARN.

Type: String
thingGroupId (p. 139)

The thing group ID.

Type: String

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

Pattern: [a-zA-Z0-9\-]+
thingGroupName (p. 139)

The thing group name.

Type: String

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

139
 AWS IoT API Reference
CreateThingGroup

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

140
 AWS IoT API Reference
CreateThingType

CreateThingType
Service: AWS IoT

Creates a new thing type.

Requires permission to access the CreateThingType action.

Request Syntax
POST /thing-types/thingTypeName HTTP/1.1
Content-type: application/json

{
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"thingTypeProperties": {
"searchableAttributes": [ "string" ],
"thingTypeDescription": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

thingTypeName (p. 141)

The name of the thing type.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

tags (p. 141)

Metadata which can be used to manage the thing type.

Type: Array of Tag (p. 979) objects

Required: No
thingTypeProperties (p. 141)

The ThingTypeProperties for the thing type to create. It contains information about the new thing
type including a description, and a list of searchable thing attribute names.

Type: ThingTypeProperties (p. 998) object

Required: No

141
 AWS IoT API Reference
CreateThingType

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"thingTypeArn": "string",
"thingTypeId": "string",
"thingTypeName": "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.

thingTypeArn (p. 142)

The Amazon Resource Name (ARN) of the thing type.

Type: String
thingTypeId (p. 142)

The thing type ID.

Type: String
thingTypeName (p. 142)

The name of the thing type.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

142
 AWS IoT API Reference
CreateThingType

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

143
 AWS IoT API Reference
CreateTopicRule

CreateTopicRule
Service: AWS IoT

Creates a rule. Creating rules is an administrator-level action. Any user who has permission to create
rules will be able to access data processed by the rule.

Requires permission to access the CreateTopicRule action.

Request Syntax
POST /rules/ruleName HTTP/1.1
x-amz-tagging: tags
Content-type: application/json

{
"topicRulePayload": {
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",
"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {
"batchMode": boolean,

144
 AWS IoT API Reference
CreateTopicRule

"deliveryStreamName": "string",
"roleArn": "string",
"separator": "string"
},
"http": {
"auth": {
"sigv4": {
"roleArn": "string",
"serviceName": "string",
"signingRegion": "string"
}
},
"confirmationUrl": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"url": "string"
},
"iotAnalytics": {
"batchMode": boolean,
"channelArn": "string",
"channelName": "string",
"roleArn": "string"
},
"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",
"partition": "string",

145
 AWS IoT API Reference
CreateTopicRule

"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"republish": {
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",
"key": "string",
"roleArn": "string"
},
"salesforce": {
"token": "string",
"url": "string"
},
"sns": {
"messageFormat": "string",
"roleArn": "string",
"targetArn": "string"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},
"stepFunctions": {
"executionNamePrefix": "string",
"roleArn": "string",
"stateMachineName": "string"
},
"timestream": {
"databaseName": "string",
"dimensions": [
{
"name": "string",
"value": "string"
}
],
"roleArn": "string",
"tableName": "string",
"timestamp": {
"unit": "string",
"value": "string"
}
}
}
],
"awsIotSqlVersion": "string",
"description": "string",
"errorAction": {
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},

146
 AWS IoT API Reference
CreateTopicRule

"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",
"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {
"batchMode": boolean,
"deliveryStreamName": "string",
"roleArn": "string",
"separator": "string"
},
"http": {
"auth": {
"sigv4": {
"roleArn": "string",
"serviceName": "string",
"signingRegion": "string"
}
},
"confirmationUrl": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"url": "string"
},
"iotAnalytics": {
"batchMode": boolean,
"channelArn": "string",
"channelName": "string",
"roleArn": "string"
},

147
 AWS IoT API Reference
CreateTopicRule

"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"republish": {
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",
"key": "string",
"roleArn": "string"
},
"salesforce": {
"token": "string",
"url": "string"
},
"sns": {
"messageFormat": "string",

148
 AWS IoT API Reference
CreateTopicRule

"roleArn": "string",
"targetArn": "string"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},
"stepFunctions": {
"executionNamePrefix": "string",
"roleArn": "string",
"stateMachineName": "string"
},
"timestream": {
"databaseName": "string",
"dimensions": [
{
"name": "string",
"value": "string"
}
],
"roleArn": "string",
"tableName": "string",
"timestamp": {
"unit": "string",
"value": "string"
}
}
},
"ruleDisabled": boolean,
"sql": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 144)

The name of the rule.

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

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

Required: Yes
tags (p. 144)

Metadata which can be used to manage the topic rule.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...
For the CLI command-line parameter use format: --tags "key1=value1&key2=value2..."
For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Request Body
The request accepts the following data in JSON format.

149
 AWS IoT API Reference
CreateTopicRule

topicRulePayload (p. 144)

The rule payload.

Type: TopicRulePayload (p. 1013) object

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

SqlParseException

The Rule-SQL expression can't be parsed correctly.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

150
 AWS IoT API Reference
CreateTopicRule

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

151
 AWS IoT API Reference
CreateTopicRuleDestination

CreateTopicRuleDestination
Service: AWS IoT

Creates a topic rule destination. The destination must be confirmed prior to use.

Requires permission to access the CreateTopicRuleDestination action.

Request Syntax
POST /destinations HTTP/1.1
Content-type: application/json

{
"destinationConfiguration": {
"httpUrlConfiguration": {
"confirmationUrl": "string"
},
"vpcConfiguration": {
"roleArn": "string",
"securityGroups": [ "string" ],
"subnetIds": [ "string" ],
"vpcId": "string"
}
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

destinationConfiguration (p. 152)

The topic rule destination configuration.

Type: TopicRuleDestinationConfiguration (p. 1009) object

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"topicRuleDestination": {
"arn": "string",
"createdAt": number,
"httpUrlProperties": {
"confirmationUrl": "string"
},
"lastUpdatedAt": number,
"status": "string",
"statusReason": "string",
"vpcProperties": {

152
 AWS IoT API Reference
CreateTopicRuleDestination

"roleArn": "string",
"securityGroups": [ "string" ],
"subnetIds": [ "string" ],
"vpcId": "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.

topicRuleDestination (p. 152)

The topic rule destination.

Type: TopicRuleDestination (p. 1007) object

Errors
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

153
 AWS IoT API Reference
CreateTopicRuleDestination

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

154
 AWS IoT API Reference
DeleteAccountAuditConfiguration

DeleteAccountAuditConfiguration
Service: AWS IoT

Restores the default settings for Device Defender audits for this account. Any configuration data you
entered is deleted and all audit checks are reset to disabled.

Requires permission to access the DeleteAccountAuditConfiguration action.

Request Syntax
DELETE /audit/configuration?deleteScheduledAudits=deleteScheduledAudits HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

deleteScheduledAudits (p. 155)

If true, all scheduled audits are deleted.

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

155
 AWS IoT API Reference
DeleteAccountAuditConfiguration

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

156
 AWS IoT API Reference
DeleteAuditSuppression

DeleteAuditSuppression
Service: AWS IoT

Deletes a Device Defender audit suppression.

Requires permission to access the DeleteAuditSuppression action.

Request Syntax
POST /audit/suppressions/delete HTTP/1.1
Content-type: application/json

{
"checkName": "string",
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

checkName (p. 157)

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: Yes
resourceIdentifier (p. 157)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: Yes

Response Syntax
HTTP/1.1 200

157
 AWS IoT API Reference
DeleteAuditSuppression

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

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

158
 AWS IoT API Reference
DeleteAuthorizer

DeleteAuthorizer
Service: AWS IoT

Deletes an authorizer.

Requires permission to access the DeleteAuthorizer action.

Request Syntax
DELETE /authorizer/authorizerName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

authorizerName (p. 159)

The name of the authorizer to delete.

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

Pattern: [\w=,@-]+

Required: Yes

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
DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

159
 AWS IoT API Reference
DeleteAuthorizer

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

160
 AWS IoT API Reference
DeleteBillingGroup

DeleteBillingGroup
Service: AWS IoT

Deletes the billing group.

Requires permission to access the DeleteBillingGroup action.

Request Syntax
DELETE /billing-groups/billingGroupName?expectedVersion=expectedVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

billingGroupName (p. 161)

The name of the billing group.

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

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

Required: Yes
expectedVersion (p. 161)

The expected version of the billing group. If the version of the billing group does not match the
expected version specified in the request, the DeleteBillingGroup request is rejected with a
VersionConflictException.

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

161
 AWS IoT API Reference
DeleteBillingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

162
 AWS IoT API Reference
DeleteCACertificate

DeleteCACertificate
Service: AWS IoT

Deletes a registered CA certificate.

Requires permission to access the DeleteCACertificate action.

Request Syntax
DELETE /cacertificate/caCertificateId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

caCertificateId (p. 163)

The ID of the certificate to delete. (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
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
CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

163
 AWS IoT API Reference
DeleteCACertificate

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

164
 AWS IoT API Reference
DeleteCertificate

DeleteCertificate
Service: AWS IoT

Deletes the specified certificate.

A certificate cannot be deleted if it has a policy or IoT thing attached to it or if its status is set to ACTIVE.
To delete a certificate, first use the DetachPolicy (p. 317) action to detach all policies. Next, use the
UpdateCertificate (p. 607) action to set the certificate to the INACTIVE status.

Requires permission to access the DeleteCertificate action.

Request Syntax
DELETE /certificates/certificateId?forceDelete=forceDelete HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 165)

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
forceDelete (p. 165)

Forces the deletion of a certificate if it is inactive and is not attached to an IoT thing.

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
CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

165
 AWS IoT API Reference
DeleteCertificate

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

166
 AWS IoT API Reference
DeleteCustomMetric

DeleteCustomMetric
Service: AWS IoT

Deletes a Device Defender detect custom metric.

Requires permission to access the DeleteCustomMetric action.

Note
Before you can delete a custom metric, you must first remove the custom metric from all
security profiles it's a part of. The security profile associated with the custom metric can be
found using the ListSecurityProfiles API with metricName set to your custom metric name.

Request Syntax
DELETE /custom-metric/metricName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 167)

The name of the custom metric.

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

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

Required: Yes

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

167
 AWS IoT API Reference
DeleteCustomMetric

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

168
 AWS IoT API Reference
DeleteDimension

DeleteDimension
Service: AWS IoT

Removes the specified dimension from your AWS accounts.

Requires permission to access the DeleteDimension action.

Request Syntax
DELETE /dimensions/name HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

name (p. 169)

The unique identifier for the dimension that you want to delete.

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

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

Required: Yes

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

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

169
 AWS IoT API Reference
DeleteDimension

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

170
 AWS IoT API Reference
DeleteDomainConfiguration

DeleteDomainConfiguration
Service: AWS IoT

Deletes the specified domain configuration.

Requires permission to access the DeleteDomainConfiguration action.

Request Syntax
DELETE /domainConfigurations/domainConfigurationName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 171)

The name of the domain configuration to be deleted.

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

Pattern: [\w.-]+

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

171
 AWS IoT API Reference
DeleteDomainConfiguration

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

172
 AWS IoT API Reference
DeleteDynamicThingGroup

DeleteDynamicThingGroup
Service: AWS IoT

Deletes a dynamic thing group.

Requires permission to access the DeleteDynamicThingGroup action.

Request Syntax
DELETE /dynamic-thing-groups/thingGroupName?expectedVersion=expectedVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 173)

The expected version of the dynamic thing group to delete.

thingGroupName (p. 173)

The name of the dynamic thing group to delete.

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

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

Required: Yes

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

173
 AWS IoT API Reference
DeleteDynamicThingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

174
 AWS IoT API Reference
DeleteFleetMetric

DeleteFleetMetric
Service: AWS IoT

Deletes the specified fleet metric. Returns successfully with no error if the deletion is successful or you
specify a fleet metric that doesn't exist.

Requires permission to access the DeleteFleetMetric action.

Request Syntax
DELETE /fleet-metric/metricName?expectedVersion=expectedVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 175)

The expected version of the fleet metric to delete.

metricName (p. 175)

The name of the fleet metric to delete.

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

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

Required: Yes

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

175
 AWS IoT API Reference
DeleteFleetMetric

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

176
 AWS IoT API Reference
DeleteJob

DeleteJob
Service: AWS IoT

Deletes a job and its related job executions.

Deleting a job may take time, depending on the number of job executions created for the job
and various other factors. While the job is being deleted, the status of the job will be shown
as "DELETION_IN_PROGRESS". Attempting to delete or cancel a job whose status is already
"DELETION_IN_PROGRESS" will result in an error.

Only 10 jobs may have status "DELETION_IN_PROGRESS" at the same time, or a LimitExceededException
will occur.

Requires permission to access the DeleteJob action.

Request Syntax
DELETE /jobs/jobId?force=force&namespaceId=namespaceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

force (p. 177)

(Optional) When true, you can delete a job which is "IN_PROGRESS". Otherwise, you can only delete
a job which is in a terminal state ("COMPLETED" or "CANCELED") or an exception will occur. The
default is false.
Note
Deleting a job which is "IN_PROGRESS", will cause a device which is executing the job to be
unable to access job information or update the job execution status. Use caution and ensure
that each device executing a job which is deleted is able to recover to a valid state.
jobId (p. 177)

The ID of the job to be deleted.

After a job deletion is completed, you may reuse this jobId when you create a new job. However, this
is not recommended, and you must ensure that your devices are not using the jobId to refer to the
deleted job.

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

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

Required: Yes
namespaceId (p. 177)

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 notifications 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.

177
 AWS IoT API Reference
DeleteJob

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

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

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
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

InvalidStateTransitionException

An attempt was made to change to an invalid state, for example by deleting a job or a job execution
which is "IN_PROGRESS" without setting the force parameter.

HTTP Status Code: 409

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

178
 AWS IoT API Reference
DeleteJob

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

179
 AWS IoT API Reference
DeleteJobExecution

DeleteJobExecution
Service: AWS IoT

Deletes a job execution.

Requires permission to access the DeleteJobExecution action.

Request Syntax
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?
force=force&namespaceId=namespaceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

executionNumber (p. 180)

The ID of the job execution to be deleted. The executionNumber refers to the execution of a
particular job on a particular device.

Note that once a job execution is deleted, the executionNumber may be reused by IoT, so be sure
you get and use the correct value here.

Required: Yes
force (p. 180)

(Optional) When true, you can delete a job execution which is "IN_PROGRESS". Otherwise, you
can only delete a job execution which is in a terminal state ("SUCCEEDED", "FAILED", "REJECTED",
"REMOVED" or "CANCELED") or an exception will occur. The default is false.
Note
Deleting a job execution which is "IN_PROGRESS", will cause the device to be unable to
access job information or update the job execution status. Use caution and ensure that the
device is able to recover to a valid state.
jobId (p. 180)

The ID of the job whose execution on a particular device will be deleted.

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

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

Required: Yes
namespaceId (p. 180)

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 notifications 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.

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

180
 AWS IoT API Reference
DeleteJobExecution

Pattern: [a-zA-Z0-9_-]+
thingName (p. 180)

The name of the thing whose job execution will be deleted.

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

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

Required: Yes

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
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

InvalidStateTransitionException

An attempt was made to change to an invalid state, for example by deleting a job or a job execution
which is "IN_PROGRESS" without setting the force parameter.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

181
 AWS IoT API Reference
DeleteJobExecution

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

182
 AWS IoT API Reference
DeleteJobTemplate

DeleteJobTemplate
Service: AWS IoT

Deletes the specified job template.

Request Syntax
DELETE /job-templates/jobTemplateId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

jobTemplateId (p. 183)

The unique identifier of the job template to delete.

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

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

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

183
 AWS IoT API Reference
DeleteJobTemplate

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

184
 AWS IoT API Reference
DeleteMitigationAction

DeleteMitigationAction
Service: AWS IoT

Deletes a defined mitigation action from your AWS accounts.

Requires permission to access the DeleteMitigationAction action.

Request Syntax
DELETE /mitigationactions/actions/actionName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

actionName (p. 185)

The name of the mitigation action that you want to delete.

Length Constraints: Maximum length of 128.

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

Required: Yes

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

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

185
 AWS IoT API Reference
DeleteMitigationAction

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

186
 AWS IoT API Reference
DeleteOTAUpdate

DeleteOTAUpdate
Service: AWS IoT

Delete an OTA update.

Requires permission to access the DeleteOTAUpdate action.

Request Syntax
DELETE /otaUpdates/otaUpdateId?
deleteStream=deleteStream&forceDeleteAWSJob=forceDeleteAWSJob HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

deleteStream (p. 187)

When true, the stream created by the OTAUpdate process is deleted when the OTA update is
deleted. Ignored if the stream specified in the OTAUpdate is supplied by the user.
forceDeleteAWSJob (p. 187)

When true, deletes the AWS IoT job created by the OTAUpdate process even if it is "IN_PROGRESS".
Otherwise, if the job is not in a terminal state ("COMPLETED" or "CANCELED") an exception will
occur. The default is false.
otaUpdateId (p. 187)

The ID of the OTA update to delete.

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

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

Required: Yes

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

187
 AWS IoT API Reference
DeleteOTAUpdate

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

188
 AWS IoT API Reference
DeletePolicy

DeletePolicy
Service: AWS IoT

Deletes the specified policy.

A policy cannot be deleted if it has non-default versions or it is attached to any certificate.

To delete a policy, use the DeletePolicyVersion (p. 191) action to delete all non-default versions of the
policy; use the DetachPolicy (p. 317) action to detach the policy from any certificate; and then use the
DeletePolicy action to delete the policy.

When a policy is deleted using DeletePolicy, its default version is deleted with it.
Note
Because of the distributed nature of AWS, it can take up to five minutes after a policy is
detached before it's ready to be deleted.

Requires permission to access the DeletePolicy action.

Request Syntax
DELETE /policies/policyName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 189)

The name of the policy to delete.

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

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

Required: Yes

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
DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

189
 AWS IoT API Reference
DeletePolicy

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

190
 AWS IoT API Reference
DeletePolicyVersion

DeletePolicyVersion
Service: AWS IoT

Deletes the specified version of the specified policy. You cannot delete the default version of a policy
using this action. To delete the default version of a policy, use DeletePolicy (p. 189). To find out which
version of a policy is marked as the default version, use ListPolicyVersions.

Requires permission to access the DeletePolicyVersion action.

Request Syntax
DELETE /policies/policyName/version/policyVersionId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 191)

The name of the policy.

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

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

Required: Yes
policyVersionId (p. 191)

The policy version ID.

Pattern: [0-9]+

Required: Yes

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
DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

HTTP Status Code: 409

191
 AWS IoT API Reference
DeletePolicyVersion

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

192
 AWS IoT API Reference
DeleteProvisioningTemplate

DeleteProvisioningTemplate
Service: AWS IoT

Deletes a fleet provisioning template.

Requires permission to access the DeleteProvisioningTemplate action.

Request Syntax
DELETE /provisioning-templates/templateName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 193)

The name of the fleet provision template to delete.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

193
 AWS IoT API Reference
DeleteProvisioningTemplate

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

194
 AWS IoT API Reference
DeleteProvisioningTemplateVersion

DeleteProvisioningTemplateVersion
Service: AWS IoT

Deletes a fleet provisioning template version.

Requires permission to access the DeleteProvisioningTemplateVersion action.

Request Syntax
DELETE /provisioning-templates/templateName/versions/versionId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 195)

The name of the fleet provisioning template version to delete.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes
versionId (p. 195)

The fleet provisioning template version ID to delete.

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

195
 AWS IoT API Reference
DeleteProvisioningTemplateVersion

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

196
 AWS IoT API Reference
DeleteRegistrationCode

DeleteRegistrationCode
Service: AWS IoT

Deletes a CA certificate registration code.

Requires permission to access the DeleteRegistrationCode action.

Request Syntax
DELETE /registrationcode HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

197
 AWS IoT API Reference
DeleteRegistrationCode

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

198
 AWS IoT API Reference
DeleteRoleAlias

DeleteRoleAlias
Service: AWS IoT

Deletes a role alias

Requires permission to access the DeleteRoleAlias action.

Request Syntax
DELETE /role-aliases/roleAlias HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

roleAlias (p. 199)

The role alias to delete.

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

Pattern: [\w=,@-]+

Required: Yes

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
DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

199
 AWS IoT API Reference
DeleteRoleAlias

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

200
 AWS IoT API Reference
DeleteScheduledAudit

DeleteScheduledAudit
Service: AWS IoT

Deletes a scheduled audit.

Requires permission to access the DeleteScheduledAudit action.

Request Syntax
DELETE /audit/scheduledaudits/scheduledAuditName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

scheduledAuditName (p. 201)

The name of the scheduled audit you want to delete.

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

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

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

201
 AWS IoT API Reference
DeleteScheduledAudit

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

202
 AWS IoT API Reference
DeleteSecurityProfile

DeleteSecurityProfile
Service: AWS IoT

Deletes a Device Defender security profile.

Requires permission to access the DeleteSecurityProfile action.

Request Syntax
DELETE /security-profiles/securityProfileName?expectedVersion=expectedVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 203)

The expected version of the security profile. A new version is generated whenever the
security profile is updated. If you specify a value that is different from the actual version, a
VersionConflictException is thrown.
securityProfileName (p. 203)

The name of the security profile to be deleted.

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

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

Required: Yes

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

203
 AWS IoT API Reference
DeleteSecurityProfile

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

204
 AWS IoT API Reference
DeleteStream

DeleteStream
Service: AWS IoT

Deletes a stream.

Requires permission to access the DeleteStream action.

Request Syntax
DELETE /streams/streamId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

streamId (p. 205)

The stream ID.

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

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

Required: Yes

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
DeleteConflictException

You can't delete the resource because it is attached to one or more resources.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

205
 AWS IoT API Reference
DeleteStream

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

206
 AWS IoT API Reference
DeleteThing

DeleteThing
Service: AWS IoT

Deletes the specified thing. Returns successfully with no error if the deletion is successful or you specify a
thing that doesn't exist.

Requires permission to access the DeleteThing action.

Request Syntax
DELETE /things/thingName?expectedVersion=expectedVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 207)

The expected version of the thing record in the registry. If the version of the record in the registry
does not match the expected version specified in the request, the DeleteThing request is rejected
with a VersionConflictException.
thingName (p. 207)

The name of the thing to delete.

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

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

Required: Yes

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.

207
 AWS IoT API Reference
DeleteThing

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

208
 AWS IoT API Reference
DeleteThingGroup

DeleteThingGroup
Service: AWS IoT

Deletes a thing group.

Requires permission to access the DeleteThingGroup action.

Request Syntax
DELETE /thing-groups/thingGroupName?expectedVersion=expectedVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 209)

The expected version of the thing group to delete.

thingGroupName (p. 209)

The name of the thing group to delete.

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

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

Required: Yes

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

209
 AWS IoT API Reference
DeleteThingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

210
 AWS IoT API Reference
DeleteThingType

DeleteThingType
Service: AWS IoT

Deletes the specified thing type. You cannot delete a thing type if it has things associated with it. To
delete a thing type, first mark it as deprecated by calling DeprecateThingType (p. 219), then remove
any associated things by calling UpdateThing (p. 655) to change the thing type on any associated
thing, and finally use DeleteThingType (p. 211) to delete the thing type.

Requires permission to access the DeleteThingType action.

Request Syntax
DELETE /thing-types/thingTypeName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

thingTypeName (p. 211)

The name of the thing type.

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

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

Required: Yes

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

211
 AWS IoT API Reference
DeleteThingType

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

212
 AWS IoT API Reference
DeleteTopicRule

DeleteTopicRule
Service: AWS IoT

Deletes the rule.

Requires permission to access the DeleteTopicRule action.

Request Syntax
DELETE /rules/ruleName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 213)

The name of the rule.

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

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

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

213
 AWS IoT API Reference
DeleteTopicRule

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

214
 AWS IoT API Reference
DeleteTopicRuleDestination

DeleteTopicRuleDestination
Service: AWS IoT

Deletes a topic rule destination.

Requires permission to access the DeleteTopicRuleDestination action.

Request Syntax
DELETE /destinations/arn+ HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

arn (p. 215)

The ARN of the topic rule destination to delete.

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

215
 AWS IoT API Reference
DeleteTopicRuleDestination

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

216
 AWS IoT API Reference
DeleteV2LoggingLevel

DeleteV2LoggingLevel
Service: AWS IoT

Deletes a logging level.

Requires permission to access the DeleteV2LoggingLevel action.

Request Syntax
DELETE /v2LoggingLevel?targetName=targetName&targetType=targetType HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

targetName (p. 217)

The name of the resource for which you are configuring logging.

Required: Yes
targetType (p. 217)

The type of resource for which you are configuring logging. Must be THING_Group.

Valid Values: DEFAULT | THING_GROUP

Required: Yes

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
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

217
 AWS IoT API Reference
DeleteV2LoggingLevel

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

218
 AWS IoT API Reference
DeprecateThingType

DeprecateThingType
Service: AWS IoT

Deprecates a thing type. You can not associate new things with deprecated thing type.

Requires permission to access the DeprecateThingType action.

Request Syntax
POST /thing-types/thingTypeName/deprecate HTTP/1.1
Content-type: application/json

{
"undoDeprecate": boolean
}

URI Request Parameters

The request uses the following URI parameters.

thingTypeName (p. 219)

The name of the thing type to deprecate.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

undoDeprecate (p. 219)

Whether to undeprecate a deprecated thing type. If true, the thing type will not be deprecated
anymore and you can associate it with things.

Type: Boolean

Required: No

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.

219
 AWS IoT API Reference
DeprecateThingType

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

220
 AWS IoT API Reference
DescribeAccountAuditConfiguration

DescribeAccountAuditConfiguration
Service: AWS IoT

Gets information about the Device Defender audit settings for this account. Settings include how audit
notifications are sent and which audit checks are enabled or disabled.

Requires permission to access the DescribeAccountAuditConfiguration action.

Request Syntax
GET /audit/configuration HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"auditCheckConfigurations": {
"string" : {
"enabled": boolean
}
},
"auditNotificationTargetConfigurations": {
"string" : {
"enabled": boolean,
"roleArn": "string",
"targetArn": "string"
}
},
"roleArn": "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.

auditCheckConfigurations (p. 221)

Which audit checks are enabled and disabled for this account.

Type: String to AuditCheckConfiguration (p. 798) object map

auditNotificationTargetConfigurations (p. 221)

Information about the targets to which audit notifications are sent for this account.

Type: String to AuditNotificationTarget (p. 807) object map

221
 AWS IoT API Reference
DescribeAccountAuditConfiguration

Valid Keys: SNS

roleArn (p. 221)

The ARN of the role that grants permission to AWS IoT to access information about your devices,
policies, certificates, and other items as required when performing an audit.

On the first call to UpdateAccountAuditConfiguration, this parameter is required.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

222
 AWS IoT API Reference
DescribeAuditFinding

DescribeAuditFinding
Service: AWS IoT

Gets information about a single audit finding. Properties include the reason for noncompliance, the
severity of the issue, and the start time when the audit that returned the finding.

Requires permission to access the DescribeAuditFinding action.

Request Syntax
GET /audit/findings/findingId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

findingId (p. 223)

A unique identifier for a single audit finding. You can use this identifier to apply mitigation actions to
the finding.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"finding": {
"checkName": "string",
"findingId": "string",
"findingTime": number,
"isSuppressed": boolean,
"nonCompliantResource": {
"additionalInfo": {
"string" : "string"
},
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},

223
 AWS IoT API Reference
DescribeAuditFinding

"roleAliasArn": "string"
},
"resourceType": "string"
},
"reasonForNonCompliance": "string",
"reasonForNonComplianceCode": "string",
"relatedResources": [
{
"additionalInfo": {
"string" : "string"
},
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"resourceType": "string"
}
],
"severity": "string",
"taskId": "string",
"taskStartTime": number
}
}

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.

finding (p. 223)

The findings (results) of the audit.

Type: AuditFinding (p. 801) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

224
 AWS IoT API Reference
DescribeAuditFinding

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

225
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

DescribeAuditMitigationActionsTask
Service: AWS IoT

Gets information about an audit mitigation task that is used to apply mitigation actions to a set of audit
findings. Properties include the actions being applied, the audit checks to which they're being applied,
the task status, and aggregated task statistics.

Request Syntax
GET /audit/mitigationactions/tasks/taskId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 226)

The unique identifier for the audit mitigation task.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"actionsDefinition": [
{
"actionParams": {
"addThingsToThingGroupParams": {
"overrideDynamicGroups": boolean,
"thingGroupNames": [ "string" ]
},
"enableIoTLoggingParams": {
"logLevel": "string",
"roleArnForLogging": "string"
},
"publishFindingToSnsParams": {
"topicArn": "string"
},
"replaceDefaultPolicyVersionParams": {
"templateName": "string"
},
"updateCACertificateParams": {
"action": "string"
},
"updateDeviceCertificateParams": {
"action": "string"
}

226
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

},
"id": "string",
"name": "string",
"roleArn": "string"
}
],
"auditCheckToActionsMapping": {
"string" : [ "string" ]
},
"endTime": number,
"startTime": number,
"target": {
"auditCheckToReasonCodeFilter": {
"string" : [ "string" ]
},
"auditTaskId": "string",
"findingIds": [ "string" ]
},
"taskStatistics": {
"string" : {
"canceledFindingsCount": number,
"failedFindingsCount": number,
"skippedFindingsCount": number,
"succeededFindingsCount": number,
"totalFindingsCount": number
}
},
"taskStatus": "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.

actionsDefinition (p. 226)

Specifies the mitigation actions and their parameters that are applied as part of this task.

Type: Array of MitigationAction (p. 919) objects

auditCheckToActionsMapping (p. 226)

Specifies the mitigation actions that should be applied to specific audit checks.

Type: String to array of strings map

Array Members: Minimum number of 1 item. Maximum number of 5 items.

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+
endTime (p. 226)

The date and time when the task was completed or canceled.

Type: Timestamp
startTime (p. 226)

The date and time when the task was started.

Type: Timestamp

227
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

target (p. 226)

Identifies the findings to which the mitigation actions are applied. This can be by audit checks, by
audit task, or a set of findings.

Type: AuditMitigationActionsTaskTarget (p. 806) object

taskStatistics (p. 226)

Aggregate counts of the results when the mitigation tasks were applied to the findings for this audit
mitigation actions task.

Type: String to TaskStatisticsForAuditCheck (p. 982) object map

taskStatus (p. 226)

The current status of the task.

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

228
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

• AWS SDK for Ruby V3

229
 AWS IoT API Reference
DescribeAuditSuppression

DescribeAuditSuppression
Service: AWS IoT

Gets information about a Device Defender audit suppression.

Request Syntax
POST /audit/suppressions/describe HTTP/1.1
Content-type: application/json

{
"checkName": "string",
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

checkName (p. 230)

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: Yes
resourceIdentifier (p. 230)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: Yes

Response Syntax
HTTP/1.1 200

230
 AWS IoT API Reference
DescribeAuditSuppression

Content-type: application/json

{
"checkName": "string",
"description": "string",
"expirationDate": number,
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"suppressIndefinitely": boolean
}

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.

checkName (p. 230)

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String
description (p. 230)

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*
expirationDate (p. 230)

The epoch timestamp in seconds at which this suppression expires.

Type: Timestamp
resourceIdentifier (p. 230)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

suppressIndefinitely (p. 230)

Indicates whether a suppression should exist indefinitely or not.

Type: Boolean

231
 AWS IoT API Reference
DescribeAuditSuppression

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

232
 AWS IoT API Reference
DescribeAuditTask

DescribeAuditTask
Service: AWS IoT

Gets information about a Device Defender audit.

Requires permission to access the DescribeAuditTask action.

Request Syntax
GET /audit/tasks/taskId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 233)

The ID of the audit whose information you want to get.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"auditDetails": {
"string" : {
"checkCompliant": boolean,
"checkRunStatus": "string",
"errorCode": "string",
"message": "string",
"nonCompliantResourcesCount": number,
"suppressedNonCompliantResourcesCount": number,
"totalResourcesCount": number
}
},
"scheduledAuditName": "string",
"taskStartTime": number,
"taskStatistics": {
"canceledChecks": number,
"compliantChecks": number,
"failedChecks": number,
"inProgressChecks": number,
"nonCompliantChecks": number,
"totalChecks": number,
"waitingForDataCollectionChecks": number
},
"taskStatus": "string",

233
 AWS IoT API Reference
DescribeAuditTask

"taskType": "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.

auditDetails (p. 233)

Detailed information about each check performed during this audit.

Type: String to AuditCheckDetails (p. 799) object map

scheduledAuditName (p. 233)

The name of the scheduled audit (only if the audit was a scheduled audit).

Type: String

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

Pattern: [a-zA-Z0-9_-]+
taskStartTime (p. 233)

The time the audit started.

Type: Timestamp
taskStatistics (p. 233)

Statistical information about the audit.

Type: TaskStatistics (p. 980) object

taskStatus (p. 233)

The status of the audit: one of "IN_PROGRESS", "COMPLETED", "FAILED", or "CANCELED".

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

taskType (p. 233)

The type of audit: "ON_DEMAND_AUDIT_TASK" or "SCHEDULED_AUDIT_TASK".

Type: String

Valid Values: ON_DEMAND_AUDIT_TASK | SCHEDULED_AUDIT_TASK

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

234
 AWS IoT API Reference
DescribeAuditTask

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

235
 AWS IoT API Reference
DescribeAuthorizer

DescribeAuthorizer
Service: AWS IoT

Describes an authorizer.

Requires permission to access the DescribeAuthorizer action.

Request Syntax
GET /authorizer/authorizerName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

authorizerName (p. 236)

The name of the authorizer to describe.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizerDescription": {
"authorizerArn": "string",
"authorizerFunctionArn": "string",
"authorizerName": "string",
"creationDate": number,
"lastModifiedDate": number,
"signingDisabled": boolean,
"status": "string",
"tokenKeyName": "string",
"tokenSigningPublicKeys": {
"string" : "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.

236
 AWS IoT API Reference
DescribeAuthorizer

authorizerDescription (p. 236)

The authorizer description.

Type: AuthorizerDescription (p. 813) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

237
 AWS IoT API Reference
DescribeBillingGroup

DescribeBillingGroup
Service: AWS IoT

Returns information about a billing group.

Requires permission to access the DescribeBillingGroup action.

Request Syntax
GET /billing-groups/billingGroupName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

billingGroupName (p. 238)

The name of the billing group.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"billingGroupArn": "string",
"billingGroupId": "string",
"billingGroupMetadata": {
"creationDate": number
},
"billingGroupName": "string",
"billingGroupProperties": {
"billingGroupDescription": "string"
},
"version": number
}

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.

billingGroupArn (p. 238)

The ARN of the billing group.

238
 AWS IoT API Reference
DescribeBillingGroup

Type: String
billingGroupId (p. 238)

The ID of the billing group.

Type: String

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

Pattern: [a-zA-Z0-9\-]+
billingGroupMetadata (p. 238)

Additional information about the billing group.

Type: BillingGroupMetadata (p. 831) object

billingGroupName (p. 238)

The name of the billing group.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
billingGroupProperties (p. 238)

The properties of the billing group.

Type: BillingGroupProperties (p. 832) object

version (p. 238)

The version of the billing group.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

239
 AWS IoT API Reference
DescribeBillingGroup

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

240
 AWS IoT API Reference
DescribeCACertificate

DescribeCACertificate
Service: AWS IoT

Describes a registered CA certificate.

Requires permission to access the DescribeCACertificate action.

Request Syntax
GET /cacertificate/caCertificateId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

caCertificateId (p. 241)

The CA certificate identifier.

Length Constraints: Fixed length of 64.

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateDescription": {
"autoRegistrationStatus": "string",
"certificateArn": "string",
"certificateId": "string",
"certificatePem": "string",
"creationDate": number,
"customerVersion": number,
"generationId": "string",
"lastModifiedDate": number,
"ownedBy": "string",
"status": "string",
"validity": {
"notAfter": number,
"notBefore": number
}
},
"registrationConfig": {
"roleArn": "string",
"templateBody": "string"
}
}

241
 AWS IoT API Reference
DescribeCACertificate

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.

certificateDescription (p. 241)

The CA certificate description.

Type: CACertificateDescription (p. 836) object

registrationConfig (p. 241)

Information about the registration configuration.

Type: RegistrationConfig (p. 947) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

242
 AWS IoT API Reference
DescribeCACertificate

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

243
 AWS IoT API Reference
DescribeCertificate

DescribeCertificate
Service: AWS IoT

Gets information about the specified certificate.

Requires permission to access the DescribeCertificate action.

Request Syntax
GET /certificates/certificateId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 244)

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
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateDescription": {
"caCertificateId": "string",
"certificateArn": "string",
"certificateId": "string",
"certificateMode": "string",
"certificatePem": "string",
"creationDate": number,
"customerVersion": number,
"generationId": "string",
"lastModifiedDate": number,
"ownedBy": "string",
"previousOwnedBy": "string",
"status": "string",
"transferData": {
"acceptDate": number,
"rejectDate": number,
"rejectReason": "string",
"transferDate": number,
"transferMessage": "string"
},
"validity": {
"notAfter": number,
"notBefore": number

244
 AWS IoT API Reference
DescribeCertificate

}
}
}

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.

certificateDescription (p. 244)

The description of the certificate.

Type: CertificateDescription (p. 840) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

245
 AWS IoT API Reference
DescribeCertificate

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

246
 AWS IoT API Reference
DescribeCustomMetric

DescribeCustomMetric
Service: AWS IoT

Gets information about a Device Defender detect custom metric.

Requires permission to access the DescribeCustomMetric action.

Request Syntax
GET /custom-metric/metricName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 247)

The name of the custom metric.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"displayName": "string",
"lastModifiedDate": number,
"metricArn": "string",
"metricName": "string",
"metricType": "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.

creationDate (p. 247)

The creation date of the custom metric in milliseconds since epoch.

Type: Timestamp

247
 AWS IoT API Reference
DescribeCustomMetric

displayName (p. 247)

Field represents a friendly name in the console for the custom metric; doesn't have to be unique.
Don't use this name as the metric identifier in the device metric report. Can be updated.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Graph}\x20]*
lastModifiedDate (p. 247)

The time the custom metric was last modified in milliseconds since epoch.

Type: Timestamp
metricArn (p. 247)

The Amazon Resource Number (ARN) of the custom metric.

Type: String
metricName (p. 247)

The name of the custom metric.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
metricType (p. 247)

The type of the custom metric. Types include string-list, ip-address-list, number-list,
and number.

Type: String

Valid Values: string-list | ip-address-list | number-list | number

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

248
 AWS IoT API Reference
DescribeCustomMetric

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

249
 AWS IoT API Reference
DescribeDefaultAuthorizer

DescribeDefaultAuthorizer
Service: AWS IoT

Describes the default authorizer.

Requires permission to access the DescribeDefaultAuthorizer action.

Request Syntax
GET /default-authorizer HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizerDescription": {
"authorizerArn": "string",
"authorizerFunctionArn": "string",
"authorizerName": "string",
"creationDate": number,
"lastModifiedDate": number,
"signingDisabled": boolean,
"status": "string",
"tokenKeyName": "string",
"tokenSigningPublicKeys": {
"string" : "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.

authorizerDescription (p. 250)

The default authorizer's description.

Type: AuthorizerDescription (p. 813) object

Errors
InternalFailureException

An unexpected error has occurred.

250
 AWS IoT API Reference
DescribeDefaultAuthorizer

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

251
 AWS IoT API Reference
DescribeDetectMitigationActionsTask

DescribeDetectMitigationActionsTask
Service: AWS IoT

Gets information about a Device Defender ML Detect mitigation action.

Requires permission to access the DescribeDetectMitigationActionsTask action.

Request Syntax
GET /detect/mitigationactions/tasks/taskId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 252)

The unique identifier of the task.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"taskSummary": {
"actionsDefinition": [
{
"actionParams": {
"addThingsToThingGroupParams": {
"overrideDynamicGroups": boolean,
"thingGroupNames": [ "string" ]
},
"enableIoTLoggingParams": {
"logLevel": "string",
"roleArnForLogging": "string"
},
"publishFindingToSnsParams": {
"topicArn": "string"
},
"replaceDefaultPolicyVersionParams": {
"templateName": "string"
},
"updateCACertificateParams": {
"action": "string"
},
"updateDeviceCertificateParams": {

252
 AWS IoT API Reference
DescribeDetectMitigationActionsTask

"action": "string"
}
},
"id": "string",
"name": "string",
"roleArn": "string"
}
],
"onlyActiveViolationsIncluded": boolean,
"suppressedAlertsIncluded": boolean,
"target": {
"behaviorName": "string",
"securityProfileName": "string",
"violationIds": [ "string" ]
},
"taskEndTime": number,
"taskId": "string",
"taskStartTime": number,
"taskStatistics": {
"actionsExecuted": number,
"actionsFailed": number,
"actionsSkipped": number
},
"taskStatus": "string",
"violationEventOccurrenceRange": {
"endTime": number,
"startTime": number
}
}
}

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.

taskSummary (p. 252)

The description of a task.

Type: DetectMitigationActionsTaskSummary (p. 858) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

253
 AWS IoT API Reference
DescribeDetectMitigationActionsTask

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

254
 AWS IoT API Reference
DescribeDimension

DescribeDimension
Service: AWS IoT

Provides details about a dimension that is defined in your AWS accounts.

Requires permission to access the DescribeDimension action.

Request Syntax
GET /dimensions/name HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

name (p. 255)

The unique identifier for the dimension.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"arn": "string",
"creationDate": number,
"lastModifiedDate": number,
"name": "string",
"stringValues": [ "string" ],
"type": "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.

arn (p. 255)

The Amazon Resource Name (ARN) for the dimension.

Type: String

255
 AWS IoT API Reference
DescribeDimension

creationDate (p. 255)

The date the dimension was created.

Type: Timestamp
lastModifiedDate (p. 255)

The date the dimension was last modified.

Type: Timestamp
name (p. 255)

The unique identifier for the dimension.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
stringValues (p. 255)

The value or list of values used to scope the dimension. For example, for topic filters, this is the
pattern used to match the MQTT topic name.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

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

type (p. 255)

The type of the dimension.

Type: String

Valid Values: TOPIC_FILTER

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

256
 AWS IoT API Reference
DescribeDimension

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

257
 AWS IoT API Reference
DescribeDomainConfiguration

DescribeDomainConfiguration
Service: AWS IoT

Gets summary information about a domain configuration.

Requires permission to access the DescribeDomainConfiguration action.

Request Syntax
GET /domainConfigurations/domainConfigurationName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 258)

The name of the domain configuration.

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

Pattern: [\w.:-]+

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizerConfig": {
"allowAuthorizerOverride": boolean,
"defaultAuthorizerName": "string"
},
"domainConfigurationArn": "string",
"domainConfigurationName": "string",
"domainConfigurationStatus": "string",
"domainName": "string",
"domainType": "string",
"lastStatusChangeDate": number,
"serverCertificates": [
{
"serverCertificateArn": "string",
"serverCertificateStatus": "string",
"serverCertificateStatusDetail": "string"
}
],
"serviceType": "string"
}

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

258
 AWS IoT API Reference
DescribeDomainConfiguration

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

authorizerConfig (p. 258)

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 812) object

domainConfigurationArn (p. 258)

The ARN of the domain configuration.

Type: String
domainConfigurationName (p. 258)

The name of the domain configuration.

Type: String

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

Pattern: [\w.:-]+
domainConfigurationStatus (p. 258)

A Boolean value that specifies the current state of the domain configuration.

Type: String

Valid Values: ENABLED | DISABLED

domainName (p. 258)

The name of the domain.

Type: String

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

domainType (p. 258)

The type of the domain.

Type: String

Valid Values: ENDPOINT | AWS_MANAGED | CUSTOMER_MANAGED

lastStatusChangeDate (p. 258)

The date and time the domain configuration's status was last changed.

Type: Timestamp
serverCertificates (p. 258)

A list containing summary information about the server certificate included in the domain
configuration.

Type: Array of ServerCertificateSummary (p. 964) objects

serviceType (p. 258)

The type of service delivered by the endpoint.

Type: String

Valid Values: DATA | CREDENTIAL_PROVIDER | JOBS

259
 AWS IoT API Reference
DescribeDomainConfiguration

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

260
 AWS IoT API Reference
DescribeEndpoint

DescribeEndpoint
Service: AWS IoT

Returns a unique endpoint specific to the AWS account making the call.

Requires permission to access the DescribeEndpoint action.

Request Syntax
GET /endpoint?endpointType=endpointType HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

endpointType (p. 261)

The endpoint type. Valid endpoint types include:

• iot:Data - Returns a VeriSign signed data endpoint.
• iot:Data-ATS - Returns an ATS signed data endpoint.
• iot:CredentialProvider - Returns an AWS IoT credentials provider API endpoint.
• iot:Jobs - Returns an AWS IoT device management Jobs API endpoint.

We strongly recommend that customers use the newer iot:Data-ATS endpoint type to avoid
issues related to the widespread distrust of Symantec certificate authorities.

Length Constraints: Maximum length of 128.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"endpointAddress": "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.

endpointAddress (p. 261)

The endpoint. The format of the endpoint is as follows: identifier.iot.region.amazonaws.com.

Type: String

261
 AWS IoT API Reference
DescribeEndpoint

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

262
 AWS IoT API Reference
DescribeEventConfigurations

DescribeEventConfigurations
Service: AWS IoT

Describes event configurations.

Requires permission to access the DescribeEventConfigurations action.

Request Syntax
GET /event-configurations HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"eventConfigurations": {
"string" : {
"Enabled": boolean
}
},
"lastModifiedDate": number
}

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.

creationDate (p. 263)

The creation date of the event configuration.

Type: Timestamp
eventConfigurations (p. 263)

The event configurations.

Type: String to Configuration (p. 851) object map

Valid Keys: THING | THING_GROUP | THING_TYPE | THING_GROUP_MEMBERSHIP |

THING_GROUP_HIERARCHY | THING_TYPE_ASSOCIATION | JOB | JOB_EXECUTION |
POLICY | CERTIFICATE | CA_CERTIFICATE
lastModifiedDate (p. 263)

The date the event configurations were last modified.

263
 AWS IoT API Reference
DescribeEventConfigurations

Type: Timestamp

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

264
 AWS IoT API Reference
DescribeFleetMetric

DescribeFleetMetric
Service: AWS IoT

Gets information about the specified fleet metric.

Requires permission to access the DescribeFleetMetric action.

Request Syntax
GET /fleet-metric/metricName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 265)

The name of the fleet metric to describe.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"aggregationField": "string",
"aggregationType": {
"name": "string",
"values": [ "string" ]
},
"creationDate": number,
"description": "string",
"indexName": "string",
"lastModifiedDate": number,
"metricArn": "string",
"metricName": "string",
"period": number,
"queryString": "string",
"queryVersion": "string",
"unit": "string",
"version": number
}

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

265
 AWS IoT API Reference
DescribeFleetMetric

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

aggregationField (p. 265)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

aggregationType (p. 265)

The type of the aggregation query.

Type: AggregationType (p. 791) object

creationDate (p. 265)

The date when the fleet metric is created.

Type: Timestamp
description (p. 265)

The fleet metric description.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [\p{Graph}\x20]*
indexName (p. 265)

The name of the index to search.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
lastModifiedDate (p. 265)

The date when the fleet metric is last modified.

Type: Timestamp
metricArn (p. 265)

The ARN of the fleet metric to describe.

Type: String
metricName (p. 265)

The name of the fleet metric to describe.

Type: String

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

Pattern: [a-zA-Z0-9_\-\.]+
period (p. 265)

The time in seconds between fleet metric emissions. Range [60(1 min), 86400(1 day)] and must be
multiple of 60.

266
 AWS IoT API Reference
DescribeFleetMetric

Type: Integer

Valid Range: Minimum value of 60. Maximum value of 86400.

queryString (p. 265)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 265)

The query version.

Type: String
unit (p. 265)

Used to support unit transformation such as milliseconds to seconds. The unit must be supported by
CW metric.

Type: String

Valid Values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes |

Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits
| Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/
Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second
| Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None
version (p. 265)

The version of the fleet metric.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

267
 AWS IoT API Reference
DescribeFleetMetric

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

268
 AWS IoT API Reference
DescribeIndex

DescribeIndex
Service: AWS IoT

Describes a search index.

Requires permission to access the DescribeIndex action.

Request Syntax
GET /indices/indexName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

indexName (p. 269)

The index name.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"indexName": "string",
"indexStatus": "string",
"schema": "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.

indexName (p. 269)

The index name.

Type: String

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

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

269
 AWS IoT API Reference
DescribeIndex

indexStatus (p. 269)

The index status.

Type: String

Valid Values: ACTIVE | BUILDING | REBUILDING

schema (p. 269)

Contains a value that specifies the type of indexing performed. Valid values are:
• REGISTRY – Your thing index contains only registry data.
• REGISTRY_AND_SHADOW - Your thing index contains registry data and shadow data.
• REGISTRY_AND_CONNECTIVITY_STATUS - Your thing index contains registry data and thing
connectivity status data.
• REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS - Your thing index contains registry data,
shadow data, and thing connectivity status data.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

270
 AWS IoT API Reference
DescribeIndex

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

271
 AWS IoT API Reference
DescribeJob

DescribeJob
Service: AWS IoT

Describes a job.

Requires permission to access the DescribeJob action.

Request Syntax
GET /jobs/jobId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 272)

The unique identifier you assigned to this job when it was created.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"documentSource": "string",
"job": {
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"comment": "string",
"completedAt": number,
"createdAt": number,
"description": "string",
"forceCanceled": boolean,
"jobArn": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {

272
 AWS IoT API Reference
DescribeJob

"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobId": "string",
"jobProcessDetails": {
"numberOfCanceledThings": number,
"numberOfFailedThings": number,
"numberOfInProgressThings": number,
"numberOfQueuedThings": number,
"numberOfRejectedThings": number,
"numberOfRemovedThings": number,
"numberOfSucceededThings": number,
"numberOfTimedOutThings": number,
"processingTargets": [ "string" ]
},
"jobTemplateArn": "string",
"lastUpdatedAt": number,
"namespaceId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"reasonCode": "string",
"status": "string",
"targets": [ "string" ],
"targetSelection": "string",
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
}

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.

documentSource (p. 272)

An S3 link to the job document.

Type: String

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

job (p. 272)

Information about the job.

Type: Job (p. 889) object

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

273
 AWS IoT API Reference
DescribeJob

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

274
 AWS IoT API Reference
DescribeJobExecution

DescribeJobExecution
Service: AWS IoT

Describes a job execution.

Requires permission to access the DescribeJobExecution action.

Request Syntax
GET /things/thingName/jobs/jobId?executionNumber=executionNumber HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

executionNumber (p. 275)

A string (consisting of the digits "0" through "9" which is used to specify a particular job execution on
a particular device.
jobId (p. 275)

The unique identifier you assigned to this job when it was created.

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

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

Required: Yes
thingName (p. 275)

The name of the thing on which the job execution is running.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"execution": {
"approximateSecondsBeforeTimedOut": number,
"executionNumber": number,
"forceCanceled": boolean,
"jobId": "string",
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,

275
 AWS IoT API Reference
DescribeJobExecution

"status": "string",
"statusDetails": {
"detailsMap": {
"string" : "string"
}
},
"thingArn": "string",
"versionNumber": number
}
}

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.

execution (p. 275)

Information about the job execution.

Type: JobExecution (p. 893) object

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

276
 AWS IoT API Reference
DescribeJobExecution

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

277
 AWS IoT API Reference
DescribeJobTemplate

DescribeJobTemplate
Service: AWS IoT

Returns information about a job template.

Request Syntax
GET /job-templates/jobTemplateId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

jobTemplateId (p. 278)

The unique identifier of the job template.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"createdAt": number,
"description": "string",
"document": "string",
"documentSource": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},

278
 AWS IoT API Reference
DescribeJobTemplate

"jobTemplateArn": "string",
"jobTemplateId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

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.

abortConfig (p. 278)

The criteria that determine when and how a job abort takes place.

Type: AbortConfig (p. 782) object

createdAt (p. 278)

The time, in seconds since the epoch, when the job template was created.

Type: Timestamp
description (p. 278)

A description of the job template.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
document (p. 278)

The job document.

Type: String

Length Constraints: Maximum length of 32768.

documentSource (p. 278)

An S3 link to the job document.

Type: String

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

jobExecutionsRolloutConfig (p. 278)

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 895) object

jobTemplateArn (p. 278)

The ARN of the job template.

Type: String

279
 AWS IoT API Reference
DescribeJobTemplate

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

Pattern: ^arn:[!-~]+$
jobTemplateId (p. 278)

The unique identifier of the job template.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
presignedUrlConfig (p. 278)

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 937) object

timeoutConfig (p. 278)

Specifies the amount of time each device has to finish its execution of the job. A timer is started
when the job execution status is set to IN_PROGRESS. If the job execution status is not set to
another terminal state before the timer expires, it will be automatically set to TIMED_OUT.

Type: TimeoutConfig (p. 999) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

280
 AWS IoT API Reference
DescribeJobTemplate

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

281
 AWS IoT API Reference
DescribeMitigationAction

DescribeMitigationAction
Service: AWS IoT

Gets information about a mitigation action.

Requires permission to access the DescribeMitigationAction action.

Request Syntax
GET /mitigationactions/actions/actionName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

actionName (p. 282)

The friendly name that uniquely identifies the mitigation action.

Length Constraints: Maximum length of 128.

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"actionArn": "string",
"actionId": "string",
"actionName": "string",
"actionParams": {
"addThingsToThingGroupParams": {
"overrideDynamicGroups": boolean,
"thingGroupNames": [ "string" ]
},
"enableIoTLoggingParams": {
"logLevel": "string",
"roleArnForLogging": "string"
},
"publishFindingToSnsParams": {
"topicArn": "string"
},
"replaceDefaultPolicyVersionParams": {
"templateName": "string"
},
"updateCACertificateParams": {
"action": "string"
},
"updateDeviceCertificateParams": {
"action": "string"

282
 AWS IoT API Reference
DescribeMitigationAction

}
},
"actionType": "string",
"creationDate": number,
"lastModifiedDate": number,
"roleArn": "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.

actionArn (p. 282)

The ARN that identifies this migration action.

Type: String
actionId (p. 282)

A unique identifier for this action.

Type: String
actionName (p. 282)

The friendly name that uniquely identifies the mitigation action.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+
actionParams (p. 282)

Parameters that control how the mitigation action is applied, specific to the type of mitigation
action.

Type: MitigationActionParams (p. 921) object

actionType (p. 282)

The type of mitigation action.

Type: String

Valid Values: UPDATE_DEVICE_CERTIFICATE | UPDATE_CA_CERTIFICATE |

ADD_THINGS_TO_THING_GROUP | REPLACE_DEFAULT_POLICY_VERSION |
ENABLE_IOT_LOGGING | PUBLISH_FINDING_TO_SNS
creationDate (p. 282)

The date and time when the mitigation action was added to your AWS accounts.

Type: Timestamp
lastModifiedDate (p. 282)

The date and time when the mitigation action was last changed.

Type: Timestamp

283
 AWS IoT API Reference
DescribeMitigationAction

roleArn (p. 282)

The ARN of the IAM role used to apply this action.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

284
 AWS IoT API Reference
DescribeProvisioningTemplate

DescribeProvisioningTemplate
Service: AWS IoT

Returns information about a fleet provisioning template.

Requires permission to access the DescribeProvisioningTemplate action.

Request Syntax
GET /provisioning-templates/templateName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 285)

The name of the fleet provisioning template.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"defaultVersionId": number,
"description": "string",
"enabled": boolean,
"lastModifiedDate": number,
"preProvisioningHook": {
"payloadVersion": "string",
"targetArn": "string"
},
"provisioningRoleArn": "string",
"templateArn": "string",
"templateBody": "string",
"templateName": "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.

285
 AWS IoT API Reference
DescribeProvisioningTemplate

creationDate (p. 285)

The date when the fleet provisioning template was created.

Type: Timestamp
defaultVersionId (p. 285)

The default fleet template version ID.

Type: Integer
description (p. 285)

The description of the fleet provisioning template.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: [^\p{C}]*
enabled (p. 285)

True if the fleet provisioning template is enabled, otherwise false.

Type: Boolean
lastModifiedDate (p. 285)

The date when the fleet provisioning template was last modified.

Type: Timestamp
preProvisioningHook (p. 285)

Gets information about a pre-provisioned hook.

Type: ProvisioningHook (p. 938) object

provisioningRoleArn (p. 285)

The ARN of the role associated with the provisioning template. This IoT role grants permission to
provision a device.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

templateArn (p. 285)

The ARN of the fleet provisioning template.

Type: String
templateBody (p. 285)

The JSON formatted contents of the fleet provisioning template.

Type: String
templateName (p. 285)

The name of the fleet provisioning template.

Type: String

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

286
 AWS IoT API Reference
DescribeProvisioningTemplate

Pattern: ^[0-9A-Za-z_-]+$

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

287
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

DescribeProvisioningTemplateVersion
Service: AWS IoT

Returns information about a fleet provisioning template version.

Requires permission to access the DescribeProvisioningTemplateVersion action.

Request Syntax
GET /provisioning-templates/templateName/versions/versionId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 288)

The template name.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes
versionId (p. 288)

The fleet provisioning template version ID.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"isDefaultVersion": boolean,
"templateBody": "string",
"versionId": number
}

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.

creationDate (p. 288)

The date when the fleet provisioning template version was created.

288
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

Type: Timestamp
isDefaultVersion (p. 288)

True if the fleet provisioning template version is the default version.

Type: Boolean
templateBody (p. 288)

The JSON formatted contents of the fleet provisioning template version.

Type: String
versionId (p. 288)

The fleet provisioning template version ID.

Type: Integer

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

289
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

290
 AWS IoT API Reference
DescribeRoleAlias

DescribeRoleAlias
Service: AWS IoT

Describes a role alias.

Requires permission to access the DescribeRoleAlias action.

Request Syntax
GET /role-aliases/roleAlias HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

roleAlias (p. 291)

The role alias to describe.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"roleAliasDescription": {
"creationDate": number,
"credentialDurationSeconds": number,
"lastModifiedDate": number,
"owner": "string",
"roleAlias": "string",
"roleAliasArn": "string",
"roleArn": "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.

roleAliasDescription (p. 291)

The role alias description.

291
 AWS IoT API Reference
DescribeRoleAlias

Type: RoleAliasDescription (p. 953) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

292
 AWS IoT API Reference
DescribeScheduledAudit

DescribeScheduledAudit
Service: AWS IoT

Gets information about a scheduled audit.

Requires permission to access the DescribeScheduledAudit action.

Request Syntax
GET /audit/scheduledaudits/scheduledAuditName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

scheduledAuditName (p. 293)

The name of the scheduled audit whose information you want to get.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"dayOfMonth": "string",
"dayOfWeek": "string",
"frequency": "string",
"scheduledAuditArn": "string",
"scheduledAuditName": "string",
"targetCheckNames": [ "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.

dayOfMonth (p. 293)

The day of the month on which the scheduled audit takes place. This is will be 1 through 31 or LAST.
If days 29-31 are specified, and the month does not have that many days, the audit takes place on
the LAST day of the month.

Type: String

293
 AWS IoT API Reference
DescribeScheduledAudit

Pattern: ^([1-9]|[12][0-9]|3[01])$|^LAST$
dayOfWeek (p. 293)

The day of the week on which the scheduled audit takes place, either one of SUN, MON, TUE, WED,
THU, FRI, or SAT.

Type: String

Valid Values: SUN | MON | TUE | WED | THU | FRI | SAT

frequency (p. 293)

How often the scheduled audit takes place, either one of DAILY, WEEKLY, BIWEEKLY, or MONTHLY.
The start time of each audit is determined by the system.

Type: String

Valid Values: DAILY | WEEKLY | BIWEEKLY | MONTHLY

scheduledAuditArn (p. 293)

The ARN of the scheduled audit.

Type: String
scheduledAuditName (p. 293)

The name of the scheduled audit.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
targetCheckNames (p. 293)

Which checks are performed during the scheduled audit. Checks must be enabled for your account.
(Use DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: Array of strings

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

294
 AWS IoT API Reference
DescribeScheduledAudit

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

295
 AWS IoT API Reference
DescribeSecurityProfile

DescribeSecurityProfile
Service: AWS IoT

Gets information about a Device Defender security profile.

Requires permission to access the DescribeSecurityProfile action.

Request Syntax
GET /security-profiles/securityProfileName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

securityProfileName (p. 296)

The name of the security profile whose information you want to get.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,

296
 AWS IoT API Reference
DescribeSecurityProfile

"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"creationDate": number,
"lastModifiedDate": number,
"securityProfileArn": "string",
"securityProfileDescription": "string",
"securityProfileName": "string",
"version": number
}

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.

additionalMetricsToRetain (p. 296)

This parameter has been deprecated.

Please use DescribeSecurityProfile:additionalMetricsToRetainV2 (p. 297) instead.

A list of metrics whose data is retained (stored). By default, data is retained for any metric used in
the profile's behaviors, but it is also retained for any metric specified here.

Type: Array of strings

additionalMetricsToRetainV2 (p. 296)

A list of metrics whose data is retained (stored). By default, data is retained for any metric used in
the profile's behaviors, but it is also retained for any metric specified here.

Type: Array of MetricToRetain (p. 916) objects

alertTargets (p. 296)

Where the alerts are sent. (Alerts are always sent to the console.)

Type: String to AlertTarget (p. 792) object map

Valid Keys: SNS

297
 AWS IoT API Reference
DescribeSecurityProfile

behaviors (p. 296)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 825) objects

Array Members: Maximum number of 100 items.

creationDate (p. 296)

The time the security profile was created.

Type: Timestamp
lastModifiedDate (p. 296)

The time the security profile was last modified.

Type: Timestamp
securityProfileArn (p. 296)

The ARN of the security profile.

Type: String
securityProfileDescription (p. 296)

A description of the security profile (associated with the security profile when it was created or
updated).

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*
securityProfileName (p. 296)

The name of the security profile.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
version (p. 296)

The version of the security profile. A new version is generated whenever the security profile is
updated.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

298
 AWS IoT API Reference
DescribeSecurityProfile

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

299
 AWS IoT API Reference
DescribeStream

DescribeStream
Service: AWS IoT

Gets information about a stream.

Requires permission to access the DescribeStream action.

Request Syntax
GET /streams/streamId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

streamId (p. 300)

The stream ID.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"streamInfo": {
"createdAt": number,
"description": "string",
"files": [
{
"fileId": number,
"s3Location": {
"bucket": "string",
"key": "string",
"version": "string"
}
}
],
"lastUpdatedAt": number,
"roleArn": "string",
"streamArn": "string",
"streamId": "string",
"streamVersion": number
}
}

300
 AWS IoT API Reference
DescribeStream

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.

streamInfo (p. 300)

Information about the stream.

Type: StreamInfo (p. 976) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

301
 AWS IoT API Reference
DescribeStream

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

302
 AWS IoT API Reference
DescribeThing

DescribeThing
Service: AWS IoT

Gets information about the specified thing.

Requires permission to access the DescribeThing action.

Request Syntax
GET /things/thingName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

thingName (p. 303)

The name of the thing.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"attributes": {
"string" : "string"
},
"billingGroupName": "string",
"defaultClientId": "string",
"thingArn": "string",
"thingId": "string",
"thingName": "string",
"thingTypeName": "string",
"version": number
}

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.

attributes (p. 303)

The thing attributes.

303
 AWS IoT API Reference
DescribeThing

Type: String to string map

Key Length Constraints: Maximum length of 128.

Key Pattern: [a-zA-Z0-9_.,@/:#-]+

Value Length Constraints: Maximum length of 800.

Value Pattern: [a-zA-Z0-9_.,@/:#-]*

billingGroupName (p. 303)

The name of the billing group the thing belongs to.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
defaultClientId (p. 303)

The default MQTT client ID. For a typical device, the thing name is also used as the default MQTT
client ID. Although we don’t require a mapping between a thing's registry name and its use of MQTT
client IDs, certificates, or shadow state, we recommend that you choose a thing name and use it as
the MQTT client ID for the registry and the Device Shadow service.

This lets you better organize your AWS IoT fleet without removing the flexibility of the underlying
device certificate model or shadows.

Type: String
thingArn (p. 303)

The ARN of the thing to describe.

Type: String
thingId (p. 303)

The ID of the thing to describe.

Type: String
thingName (p. 303)

The name of the thing.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
thingTypeName (p. 303)

The thing type name.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
version (p. 303)

The current version of the thing record in the registry.

304
 AWS IoT API Reference
DescribeThing

Note
To avoid unintentional changes to the information in the registry, you can pass the version
information in the expectedVersion parameter of the UpdateThing and DeleteThing
calls.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

305
 AWS IoT API Reference
DescribeThingGroup

DescribeThingGroup
Service: AWS IoT

Describe a thing group.

Requires permission to access the DescribeThingGroup action.

Request Syntax
GET /thing-groups/thingGroupName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

thingGroupName (p. 306)

The name of the thing group.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"indexName": "string",
"queryString": "string",
"queryVersion": "string",
"status": "string",
"thingGroupArn": "string",
"thingGroupId": "string",
"thingGroupMetadata": {
"creationDate": number,
"parentGroupName": "string",
"rootToParentThingGroups": [
{
"groupArn": "string",
"groupName": "string"
}
]
},
"thingGroupName": "string",
"thingGroupProperties": {
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean

306
 AWS IoT API Reference
DescribeThingGroup

},
"thingGroupDescription": "string"
},
"version": number
}

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.

indexName (p. 306)

The dynamic thing group index name.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
queryString (p. 306)

The dynamic thing group search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 306)

The dynamic thing group query version.

Type: String
status (p. 306)

The dynamic thing group status.

Type: String

Valid Values: ACTIVE | BUILDING | REBUILDING

thingGroupArn (p. 306)

The thing group ARN.

Type: String
thingGroupId (p. 306)

The thing group ID.

Type: String

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

Pattern: [a-zA-Z0-9\-]+
thingGroupMetadata (p. 306)

Thing group metadata.

Type: ThingGroupMetadata (p. 992) object

307
 AWS IoT API Reference
DescribeThingGroup

thingGroupName (p. 306)

The name of the thing group.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
thingGroupProperties (p. 306)

The thing group properties.

Type: ThingGroupProperties (p. 993) object

version (p. 306)

The version of the thing group.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

308
 AWS IoT API Reference
DescribeThingGroup

• AWS SDK for Ruby V3

309
 AWS IoT API Reference
DescribeThingRegistrationTask

DescribeThingRegistrationTask
Service: AWS IoT

Describes a bulk thing provisioning task.

Requires permission to access the DescribeThingRegistrationTask action.

Request Syntax
GET /thing-registration-tasks/taskId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 310)

The task ID.

Length Constraints: Maximum length of 40.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"failureCount": number,
"inputFileBucket": "string",
"inputFileKey": "string",
"lastModifiedDate": number,
"message": "string",
"percentageProgress": number,
"roleArn": "string",
"status": "string",
"successCount": number,
"taskId": "string",
"templateBody": "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.

creationDate (p. 310)

The task creation date.

310
 AWS IoT API Reference
DescribeThingRegistrationTask

Type: Timestamp
failureCount (p. 310)

The number of things that failed to be provisioned.

Type: Integer
inputFileBucket (p. 310)

The S3 bucket that contains the input file.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 256.

Pattern: [a-zA-Z0-9._-]+
inputFileKey (p. 310)

The input file key.

Type: String

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

Pattern: [a-zA-Z0-9!_.*'()-\/]+
lastModifiedDate (p. 310)

The date when the task was last modified.

Type: Timestamp
message (p. 310)

The message.

Type: String

Length Constraints: Maximum length of 2048.

percentageProgress (p. 310)

The progress of the bulk provisioning task expressed as a percentage.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 100.

roleArn (p. 310)

The role ARN that grants access to the input file bucket.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

status (p. 310)

The status of the bulk thing provisioning task.

Type: String

Valid Values: InProgress | Completed | Failed | Cancelled | Cancelling

successCount (p. 310)

The number of things successfully provisioned.

311
 AWS IoT API Reference
DescribeThingRegistrationTask

Type: Integer
taskId (p. 310)

The task ID.

Type: String

Length Constraints: Maximum length of 40.

templateBody (p. 310)

The task's template.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

312
 AWS IoT API Reference
DescribeThingRegistrationTask

• AWS SDK for Ruby V3

313
 AWS IoT API Reference
DescribeThingType

DescribeThingType
Service: AWS IoT

Gets information about the specified thing type.

Requires permission to access the DescribeThingType action.

Request Syntax
GET /thing-types/thingTypeName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

thingTypeName (p. 314)

The name of the thing type.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"thingTypeArn": "string",
"thingTypeId": "string",
"thingTypeMetadata": {
"creationDate": number,
"deprecated": boolean,
"deprecationDate": number
},
"thingTypeName": "string",
"thingTypeProperties": {
"searchableAttributes": [ "string" ],
"thingTypeDescription": "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.

314
 AWS IoT API Reference
DescribeThingType

thingTypeArn (p. 314)

The thing type ARN.

Type: String
thingTypeId (p. 314)

The thing type ID.

Type: String
thingTypeMetadata (p. 314)

The ThingTypeMetadata contains additional information about the thing type including: creation
date and time, a value indicating whether the thing type is deprecated, and a date and time when it
was deprecated.

Type: ThingTypeMetadata (p. 997) object

thingTypeName (p. 314)

The name of the thing type.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
thingTypeProperties (p. 314)

The ThingTypeProperties contains information about the thing type including description, and a list
of searchable thing attribute names.

Type: ThingTypeProperties (p. 998) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

315
 AWS IoT API Reference
DescribeThingType

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

316
 AWS IoT API Reference
DetachPolicy

DetachPolicy
Service: AWS IoT

Detaches a policy from the specified target.

Note
Because of the distributed nature of AWS, it can take up to five minutes after a policy is
detached before it's ready to be deleted.

Requires permission to access the DetachPolicy action.

Request Syntax
POST /target-policies/policyName HTTP/1.1
Content-type: application/json

{
"target": "string"
}

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 317)

The policy to detach.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

target (p. 317)

The target from which the policy will be detached.

Type: String

Required: Yes

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.

317
 AWS IoT API Reference
DetachPolicy

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

318
 AWS IoT API Reference
DetachPrincipalPolicy

DetachPrincipalPolicy
Service: AWS IoT

Removes the specified policy from the specified certificate.

Note
This action is deprecated. Please use DetachPolicy (p. 317) instead.

Requires permission to access the DetachPrincipalPolicy action.

Request Syntax
DELETE /principal-policies/policyName HTTP/1.1
x-amzn-iot-principal: principal

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 319)

The name of the policy to detach.

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

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

Required: Yes
principal (p. 319)

The principal.

Valid principals are CertificateArn (arn:aws:iot:region:accountId:cert/certificateId), thingGroupArn

(arn:aws:iot:region:accountId:thinggroup/groupName) and CognitoId (region:id).

Required: Yes

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.

319
 AWS IoT API Reference
DetachPrincipalPolicy

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

320
 AWS IoT API Reference
DetachSecurityProfile

DetachSecurityProfile
Service: AWS IoT

Disassociates a Device Defender security profile from a thing group or from this account.

Requires permission to access the DetachSecurityProfile action.

Request Syntax
DELETE /security-profiles/securityProfileName/targets?
securityProfileTargetArn=securityProfileTargetArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

securityProfileName (p. 321)

The security profile that is detached.

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

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

Required: Yes
securityProfileTargetArn (p. 321)

The ARN of the thing group from which the security profile is detached.

Required: Yes

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.

321
 AWS IoT API Reference
DetachSecurityProfile

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

322
 AWS IoT API Reference
DetachThingPrincipal

DetachThingPrincipal
Service: AWS IoT

Detaches the specified principal from the specified thing. A principal can be X.509 certificates, IAM users,
groups, and roles, Amazon Cognito identities or federated identities.
Note
This call is asynchronous. It might take several seconds for the detachment to propagate.

Requires permission to access the DetachThingPrincipal action.

Request Syntax
DELETE /things/thingName/principals HTTP/1.1
x-amzn-principal: principal

URI Request Parameters

The request uses the following URI parameters.

principal (p. 323)

If the principal is a certificate, this value must be ARN of the certificate. If the principal is an Amazon
Cognito identity, this value must be the ID of the Amazon Cognito identity.

Required: Yes
thingName (p. 323)

The name of the thing.

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

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

Required: Yes

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

323
 AWS IoT API Reference
DetachThingPrincipal

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

324
 AWS IoT API Reference
DisableTopicRule

DisableTopicRule
Service: AWS IoT

Disables the rule.

Requires permission to access the DisableTopicRule action.

Request Syntax
POST /rules/ruleName/disable HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 325)

The name of the rule to disable.

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

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

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

325
 AWS IoT API Reference
DisableTopicRule

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

326
 AWS IoT API Reference
EnableTopicRule

EnableTopicRule
Service: AWS IoT

Enables the rule.

Requires permission to access the EnableTopicRule action.

Request Syntax
POST /rules/ruleName/enable HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 327)

The name of the topic rule to enable.

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

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

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

327
 AWS IoT API Reference
EnableTopicRule

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

328
 AWS IoT API Reference
GetBehaviorModelTrainingSummaries

GetBehaviorModelTrainingSummaries
Service: AWS IoT

Returns a Device Defender's ML Detect Security Profile training model's status.

Requires permission to access the GetBehaviorModelTrainingSummaries action.

Request Syntax
GET /behavior-model-training/summaries?
maxResults=maxResults&nextToken=nextToken&securityProfileName=securityProfileName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 329)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 10.

nextToken (p. 329)

The token for the next set of results.

securityProfileName (p. 329)

The name of the security profile.

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

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

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"summaries": [
{
"behaviorName": "string",
"datapointsCollectionPercentage": number,
"lastModelRefreshDate": number,
"modelStatus": "string",
"securityProfileName": "string",
"trainingDataCollectionStartDate": number
}
]
}

329
 AWS IoT API Reference
GetBehaviorModelTrainingSummaries

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.

nextToken (p. 329)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
summaries (p. 329)

A list of all ML Detect behaviors and their model status for a given Security Profile.

Type: Array of BehaviorModelTrainingSummary (p. 829) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

330
 AWS IoT API Reference
GetBucketsAggregation

GetBucketsAggregation
Service: AWS IoT

Aggregates on indexed data with search queries pertaining to particular fields.

Requires permission to access the GetBucketsAggregation action.

Request Syntax
POST /indices/buckets HTTP/1.1
Content-type: application/json

{
"aggregationField": "string",
"bucketsAggregationType": {
"termsAggregation": {
"maxBuckets": number
}
},
"indexName": "string",
"queryString": "string",
"queryVersion": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

aggregationField (p. 331)

The aggregation field.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
bucketsAggregationType (p. 331)

The basic control of the response shape and the bucket aggregation type to perform.

Type: BucketsAggregationType (p. 834) object

Required: Yes
indexName (p. 331)

The name of the index to search.

Type: String

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

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

Required: No

331
 AWS IoT API Reference
GetBucketsAggregation

queryString (p. 331)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 331)

The version of the query.

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"buckets": [
{
"count": number,
"keyValue": "string"
}
],
"totalCount": number
}

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.

buckets (p. 332)

The main part of the response with a list of buckets. Each bucket contains a keyValue and a count.

keyValue: The aggregation field value counted for the particular bucket.

count: The number of documents that have that value.

Type: Array of Bucket (p. 833) objects

totalCount (p. 332)

The total number of documents that fit the query string criteria and contain a value for the
Aggregation field targeted in the request.

Type: Integer

Errors
IndexNotReadyException

The index is not ready.

332
 AWS IoT API Reference
GetBucketsAggregation

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

333
AWS IoT API Reference
GetBucketsAggregation

334
 AWS IoT API Reference
GetCardinality

GetCardinality
Service: AWS IoT

Returns the approximate count of unique values that match the query.

Requires permission to access the GetCardinality action.

Request Syntax
POST /indices/cardinality HTTP/1.1
Content-type: application/json

{
"aggregationField": "string",
"indexName": "string",
"queryString": "string",
"queryVersion": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

aggregationField (p. 335)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 335)

The name of the index to search.

Type: String

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

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

Required: No
queryString (p. 335)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 335)

The query version.

335
 AWS IoT API Reference
GetCardinality

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"cardinality": number
}

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.

cardinality (p. 336)

The approximate count of unique values that match the query.

Type: Integer

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

336
 AWS IoT API Reference
GetCardinality

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

337
 AWS IoT API Reference
GetEffectivePolicies

GetEffectivePolicies
Service: AWS IoT

Gets a list of the policies that have an effect on the authorization behavior of the specified device when it
connects to the AWS IoT device gateway.

Requires permission to access the GetEffectivePolicies action.

Request Syntax
POST /effective-policies?thingName=thingName HTTP/1.1
Content-type: application/json

{
"cognitoIdentityPoolId": "string",
"principal": "string"
}

URI Request Parameters

The request uses the following URI parameters.

thingName (p. 338)

The thing name.

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

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

Request Body
The request accepts the following data in JSON format.

cognitoIdentityPoolId (p. 338)

The Cognito identity pool ID.

Type: String

Required: No
principal (p. 338)

The principal. Valid principals are CertificateArn (arn:aws:iot:region:accountId:cert/certificateId),

thingGroupArn (arn:aws:iot:region:accountId:thinggroup/groupName) and CognitoId (region:id).

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

338
 AWS IoT API Reference
GetEffectivePolicies

"effectivePolicies": [
{
"policyArn": "string",
"policyDocument": "string",
"policyName": "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.

effectivePolicies (p. 338)

The effective policies.

Type: Array of EffectivePolicy (p. 865) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

339
 AWS IoT API Reference
GetEffectivePolicies

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

340
 AWS IoT API Reference
GetIndexingConfiguration

GetIndexingConfiguration
Service: AWS IoT

Gets the indexing configuration.

Requires permission to access the GetIndexingConfiguration action.

Request Syntax
GET /indexing/config HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"thingGroupIndexingConfiguration": {
"customFields": [
{
"name": "string",
"type": "string"
}
],
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"thingGroupIndexingMode": "string"
},
"thingIndexingConfiguration": {
"customFields": [
{
"name": "string",
"type": "string"
}
],
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"thingConnectivityIndexingMode": "string",
"thingIndexingMode": "string"
}
}

341
 AWS IoT API Reference
GetIndexingConfiguration

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.

thingGroupIndexingConfiguration (p. 341)

The index configuration.

Type: ThingGroupIndexingConfiguration (p. 991) object

thingIndexingConfiguration (p. 341)

Thing indexing configuration.

Type: ThingIndexingConfiguration (p. 994) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

342
 AWS IoT API Reference
GetIndexingConfiguration

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

343
 AWS IoT API Reference
GetJobDocument

GetJobDocument
Service: AWS IoT

Gets a job document.

Requires permission to access the GetJobDocument action.

Request Syntax
GET /jobs/jobId/job-document HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 344)

The unique identifier you assigned to this job when it was created.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"document": "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.

document (p. 344)

The job document content.

Type: String

Length Constraints: Maximum length of 32768.

Errors
InvalidRequestException

The request is not valid.

344
 AWS IoT API Reference
GetJobDocument

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

345
 AWS IoT API Reference
GetLoggingOptions

GetLoggingOptions
Service: AWS IoT

Gets the logging options.

NOTE: use of this command is not recommended. Use GetV2LoggingOptions instead.

Requires permission to access the GetLoggingOptions action.

Request Syntax
GET /loggingOptions HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"logLevel": "string",
"roleArn": "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.

logLevel (p. 346)

The logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

roleArn (p. 346)

The ARN of the IAM role that grants access.

Type: String

Errors
InternalException

An unexpected error has occurred.

346
 AWS IoT API Reference
GetLoggingOptions

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

347
 AWS IoT API Reference
GetOTAUpdate

GetOTAUpdate
Service: AWS IoT

Gets an OTA update.

Requires permission to access the GetOTAUpdate action.

Request Syntax
GET /otaUpdates/otaUpdateId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

otaUpdateId (p. 348)

The OTA update ID.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"otaUpdateInfo": {
"additionalParameters": {
"string" : "string"
},
"awsIotJobArn": "string",
"awsIotJobId": "string",
"awsJobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"awsJobPresignedUrlConfig": {
"expiresInSec": number
},
"creationDate": number,
"description": "string",
"errorInfo": {
"code": "string",

348
 AWS IoT API Reference
GetOTAUpdate

"message": "string"
},
"lastModifiedDate": number,
"otaUpdateArn": "string",
"otaUpdateFiles": [
{
"attributes": {
"string" : "string"
},
"codeSigning": {
"awsSignerJobId": "string",
"customCodeSigning": {
"certificateChain": {
"certificateName": "string",
"inlineDocument": "string"
},
"hashAlgorithm": "string",
"signature": {
"inlineDocument": blob
},
"signatureAlgorithm": "string"
},
"startSigningJobParameter": {
"destination": {
"s3Destination": {
"bucket": "string",
"prefix": "string"
}
},
"signingProfileName": "string",
"signingProfileParameter": {
"certificateArn": "string",
"certificatePathOnDevice": "string",
"platform": "string"
}
}
},
"fileLocation": {
"s3Location": {
"bucket": "string",
"key": "string",
"version": "string"
},
"stream": {
"fileId": number,
"streamId": "string"
}
},
"fileName": "string",
"fileType": number,
"fileVersion": "string"
}
],
"otaUpdateId": "string",
"otaUpdateStatus": "string",
"protocols": [ "string" ],
"targets": [ "string" ],
"targetSelection": "string"
}
}

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

349
 AWS IoT API Reference
GetOTAUpdate

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

otaUpdateInfo (p. 348)

The OTA update info.

Type: OTAUpdateInfo (p. 927) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

350
AWS IoT API Reference
GetOTAUpdate

351
 AWS IoT API Reference
GetPercentiles

GetPercentiles
Service: AWS IoT

Groups the aggregated values that match the query into percentile groupings. The default percentile
groupings are: 1,5,25,50,75,95,99, although you can specify your own when you call GetPercentiles.
This function returns a value for each percentile group specified (or the default percentile groupings).
The percentile group "1" contains the aggregated field value that occurs in approximately one percent
of the values that match the query. The percentile group "5" contains the aggregated field value that
occurs in approximately five percent of the values that match the query, and so on. The result is an
approximation, the more values that match the query, the more accurate the percentile values.

Requires permission to access the GetPercentiles action.

Request Syntax
POST /indices/percentiles HTTP/1.1
Content-type: application/json

{
"aggregationField": "string",
"indexName": "string",
"percents": [ number ],
"queryString": "string",
"queryVersion": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

aggregationField (p. 352)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 352)

The name of the index to search.

Type: String

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

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

Required: No
percents (p. 352)

The percentile groups returned.

352
 AWS IoT API Reference
GetPercentiles

Type: Array of doubles

Valid Range: Minimum value of 0. Maximum value of 100.

Required: No
queryString (p. 352)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 352)

The query version.

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"percentiles": [
{
"percent": number,
"value": number
}
]
}

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.

percentiles (p. 353)

The percentile values of the aggregated fields.

Type: Array of PercentPair (p. 933) objects

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

353
 AWS IoT API Reference
GetPercentiles

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

354
 AWS IoT API Reference
GetPolicy

GetPolicy
Service: AWS IoT

Gets information about the specified policy with the policy document of the default version.

Requires permission to access the GetPolicy action.

Request Syntax
GET /policies/policyName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 355)

The name of the policy.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"defaultVersionId": "string",
"generationId": "string",
"lastModifiedDate": number,
"policyArn": "string",
"policyDocument": "string",
"policyName": "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.

creationDate (p. 355)

The date the policy was created.

Type: Timestamp

355
 AWS IoT API Reference
GetPolicy

defaultVersionId (p. 355)

The default policy version ID.

Type: String

Pattern: [0-9]+
generationId (p. 355)

The generation ID of the policy.

Type: String
lastModifiedDate (p. 355)

The date the policy was last modified.

Type: Timestamp
policyArn (p. 355)

The policy ARN.

Type: String
policyDocument (p. 355)

The JSON document that describes the policy.

Type: String
policyName (p. 355)

The policy name.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

356
 AWS IoT API Reference
GetPolicy

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

357
 AWS IoT API Reference
GetPolicyVersion

GetPolicyVersion
Service: AWS IoT

Gets information about the specified policy version.

Requires permission to access the GetPolicyVersion action.

Request Syntax
GET /policies/policyName/version/policyVersionId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 358)

The name of the policy.

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

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

Required: Yes
policyVersionId (p. 358)

The policy version ID.

Pattern: [0-9]+

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"generationId": "string",
"isDefaultVersion": boolean,
"lastModifiedDate": number,
"policyArn": "string",
"policyDocument": "string",
"policyName": "string",
"policyVersionId": "string"
}

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

358
 AWS IoT API Reference
GetPolicyVersion

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

creationDate (p. 358)

The date the policy was created.

Type: Timestamp
generationId (p. 358)

The generation ID of the policy version.

Type: String
isDefaultVersion (p. 358)

Specifies whether the policy version is the default.

Type: Boolean
lastModifiedDate (p. 358)

The date the policy was last modified.

Type: Timestamp
policyArn (p. 358)

The policy ARN.

Type: String
policyDocument (p. 358)

The JSON document that describes the policy.

Type: String
policyName (p. 358)

The policy name.

Type: String

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

Pattern: [\w+=,.@-]+
policyVersionId (p. 358)

The policy version ID.

Type: String

Pattern: [0-9]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

359
 AWS IoT API Reference
GetPolicyVersion

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

360
 AWS IoT API Reference
GetRegistrationCode

GetRegistrationCode
Service: AWS IoT

Gets a registration code used to register a CA certificate with AWS IoT.

Requires permission to access the GetRegistrationCode action.

Request Syntax
GET /registrationcode HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"registrationCode": "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.

registrationCode (p. 361)

The CA certificate registration code.

Type: String

Length Constraints: Fixed length of 64.

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

361
 AWS IoT API Reference
GetRegistrationCode

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

362
 AWS IoT API Reference
GetStatistics

GetStatistics
Service: AWS IoT

Returns the count, average, sum, minimum, maximum, sum of squares, variance, and standard deviation
for the specified aggregated field. If the aggregation field is of type String, only the count statistic is
returned.

Requires permission to access the GetStatistics action.

Request Syntax
POST /indices/statistics HTTP/1.1
Content-type: application/json

{
"aggregationField": "string",
"indexName": "string",
"queryString": "string",
"queryVersion": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

aggregationField (p. 363)

The aggregation field name.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 363)

The name of the index to search. The default value is AWS_Things.

Type: String

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

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

Required: No
queryString (p. 363)

The query used to search. You can specify "*" for the query string to get the count of all indexed
things in your AWS account.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

363
 AWS IoT API Reference
GetStatistics

queryVersion (p. 363)

The version of the query used to search.

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"statistics": {
"average": number,
"count": number,
"maximum": number,
"minimum": number,
"stdDeviation": number,
"sum": number,
"sumOfSquares": number,
"variance": number
}
}

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.

statistics (p. 364)

The statistics returned by the Fleet Indexing service based on the query and aggregation field.

Type: Statistics (p. 971) object

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

364
 AWS IoT API Reference
GetStatistics

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

365
 AWS IoT API Reference
GetTopicRule

GetTopicRule
Service: AWS IoT

Gets information about the rule.

Requires permission to access the GetTopicRule action.

Request Syntax
GET /rules/ruleName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 366)

The name of the rule.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"rule": {
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",

366
 AWS IoT API Reference
GetTopicRule

"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {
"batchMode": boolean,
"deliveryStreamName": "string",
"roleArn": "string",
"separator": "string"
},
"http": {
"auth": {
"sigv4": {
"roleArn": "string",
"serviceName": "string",
"signingRegion": "string"
}
},
"confirmationUrl": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"url": "string"
},
"iotAnalytics": {
"batchMode": boolean,
"channelArn": "string",
"channelName": "string",
"roleArn": "string"
},
"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{

367
 AWS IoT API Reference
GetTopicRule

"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"republish": {
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",
"key": "string",
"roleArn": "string"
},
"salesforce": {
"token": "string",
"url": "string"
},
"sns": {
"messageFormat": "string",
"roleArn": "string",
"targetArn": "string"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},
"stepFunctions": {
"executionNamePrefix": "string",
"roleArn": "string",
"stateMachineName": "string"
},
"timestream": {
"databaseName": "string",

368
 AWS IoT API Reference
GetTopicRule

"dimensions": [
{
"name": "string",
"value": "string"
}
],
"roleArn": "string",
"tableName": "string",
"timestamp": {
"unit": "string",
"value": "string"
}
}
}
],
"awsIotSqlVersion": "string",
"createdAt": number,
"description": "string",
"errorAction": {
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",
"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {
"batchMode": boolean,
"deliveryStreamName": "string",
"roleArn": "string",

369
 AWS IoT API Reference
GetTopicRule

"separator": "string"
},
"http": {
"auth": {
"sigv4": {
"roleArn": "string",
"serviceName": "string",
"signingRegion": "string"
}
},
"confirmationUrl": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"url": "string"
},
"iotAnalytics": {
"batchMode": boolean,
"channelArn": "string",
"channelName": "string",
"roleArn": "string"
},
"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",
"partition": "string",
"topic": "string"
},

370
 AWS IoT API Reference
GetTopicRule

"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"republish": {
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",
"key": "string",
"roleArn": "string"
},
"salesforce": {
"token": "string",
"url": "string"
},
"sns": {
"messageFormat": "string",
"roleArn": "string",
"targetArn": "string"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},
"stepFunctions": {
"executionNamePrefix": "string",
"roleArn": "string",
"stateMachineName": "string"
},
"timestream": {
"databaseName": "string",
"dimensions": [
{
"name": "string",
"value": "string"
}
],
"roleArn": "string",
"tableName": "string",
"timestamp": {
"unit": "string",
"value": "string"
}
}
},
"ruleDisabled": boolean,
"ruleName": "string",
"sql": "string"
},
"ruleArn": "string"
}

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

371
 AWS IoT API Reference
GetTopicRule

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

rule (p. 366)

The rule.

Type: TopicRule (p. 1005) object

ruleArn (p. 366)

The rule ARN.

Type: String

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

372
 AWS IoT API Reference
GetTopicRuleDestination

GetTopicRuleDestination
Service: AWS IoT

Gets information about a topic rule destination.

Requires permission to access the GetTopicRuleDestination action.

Request Syntax
GET /destinations/arn+ HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

arn (p. 373)

The ARN of the topic rule destination.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"topicRuleDestination": {
"arn": "string",
"createdAt": number,
"httpUrlProperties": {
"confirmationUrl": "string"
},
"lastUpdatedAt": number,
"status": "string",
"statusReason": "string",
"vpcProperties": {
"roleArn": "string",
"securityGroups": [ "string" ],
"subnetIds": [ "string" ],
"vpcId": "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.

topicRuleDestination (p. 373)

The topic rule destination.

373
 AWS IoT API Reference
GetTopicRuleDestination

Type: TopicRuleDestination (p. 1007) object

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

374
 AWS IoT API Reference
GetV2LoggingOptions

GetV2LoggingOptions
Service: AWS IoT

Gets the fine grained logging options.

Requires permission to access the GetV2LoggingOptions action.

Request Syntax
GET /v2LoggingOptions HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"defaultLogLevel": "string",
"disableAllLogs": boolean,
"roleArn": "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.

defaultLogLevel (p. 375)

The default log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

disableAllLogs (p. 375)

Disables all logs.

Type: Boolean
roleArn (p. 375)

The IAM role ARN AWS IoT uses to write to your CloudWatch logs.

Type: String

375
 AWS IoT API Reference
GetV2LoggingOptions

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

NotConfiguredException

The resource is not configured.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

376
 AWS IoT API Reference
ListActiveViolations

ListActiveViolations
Service: AWS IoT

Lists the active violations for a given Device Defender security profile.

Requires permission to access the ListActiveViolations action.

Request Syntax
GET /active-violations?
behaviorCriteriaType=behaviorCriteriaType&listSuppressedAlerts=listSuppressedAlerts&maxResults=maxResul
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

behaviorCriteriaType (p. 377)

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

listSuppressedAlerts (p. 377)

A list of all suppressed alerts.

maxResults (p. 377)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 377)

The token for the next set of results.

securityProfileName (p. 377)

The name of the Device Defender security profile for which violations are listed.

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

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 377)

The name of the thing whose active violations are listed.

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

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

377
 AWS IoT API Reference
ListActiveViolations

{
"activeViolations": [
{
"behavior": {
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
},
"lastViolationTime": number,
"lastViolationValue": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
},
"securityProfileName": "string",
"thingName": "string",
"violationEventAdditionalInfo": {
"confidenceLevel": "string"
},
"violationId": "string",
"violationStartTime": number
}
],
"nextToken": "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.

activeViolations (p. 377)

The list of active violations.

Type: Array of ActiveViolation (p. 788) objects

378
 AWS IoT API Reference
ListActiveViolations

nextToken (p. 377)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

379
 AWS IoT API Reference
ListAttachedPolicies

ListAttachedPolicies
Service: AWS IoT

Lists the policies attached to the specified thing group.

Requires permission to access the ListAttachedPolicies action.

Request Syntax
POST /attached-policies/target?marker=marker&pageSize=pageSize&recursive=recursive HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

marker (p. 380)

The token to retrieve the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 380)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

recursive (p. 380)

When true, recursively list attached policies.

target (p. 380)

The group or principal for which the policies will be listed. Valid principals are
CertificateArn (arn:aws:iot:region:accountId:cert/certificateId), thingGroupArn
(arn:aws:iot:region:accountId:thinggroup/groupName) and CognitoId (region:id).

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",
"policies": [
{
"policyArn": "string",
"policyName": "string"
}
]

380
 AWS IoT API Reference
ListAttachedPolicies

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.

nextMarker (p. 380)

The token to retrieve the next set of results, or ``null`` if there are no more results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
policies (p. 380)

The policies.

Type: Array of Policy (p. 934) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

381
 AWS IoT API Reference
ListAttachedPolicies

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

382
 AWS IoT API Reference
ListAuditFindings

ListAuditFindings
Service: AWS IoT

Lists the findings (results) of a Device Defender audit or of the audits performed during a specified time
period. (Findings are retained for 90 days.)

Requires permission to access the ListAuditFindings action.

Request Syntax
POST /audit/findings HTTP/1.1
Content-type: application/json

{
"checkName": "string",
"endTime": number,
"listSuppressedFindings": boolean,
"maxResults": number,
"nextToken": "string",
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"startTime": number,
"taskId": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

checkName (p. 383)

A filter to limit results to the findings for the specified audit check.

Type: String

Required: No
endTime (p. 383)

A filter to limit results to those found before the specified time. You must specify either the
startTime and endTime or the taskId, but not both.

Type: Timestamp

Required: No

383
 AWS IoT API Reference
ListAuditFindings

listSuppressedFindings (p. 383)

Boolean flag indicating whether only the suppressed findings or the unsuppressed findings should
be listed. If this parameter isn't provided, the response will list both suppressed and unsuppressed
findings.

Type: Boolean

Required: No
maxResults (p. 383)

The maximum number of results to return at one time. The default is 25.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 250.

Required: No
nextToken (p. 383)

The token for the next set of results.

Type: String

Required: No
resourceIdentifier (p. 383)

Information identifying the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: No
startTime (p. 383)

A filter to limit results to those found after the specified time. You must specify either the startTime
and endTime or the taskId, but not both.

Type: Timestamp

Required: No
taskId (p. 383)

A filter to limit results to the audit with the specified ID. You must specify either the taskId or the
startTime and endTime, but not both.

Type: String

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

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

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"findings": [

384
 AWS IoT API Reference
ListAuditFindings

{
"checkName": "string",
"findingId": "string",
"findingTime": number,
"isSuppressed": boolean,
"nonCompliantResource": {
"additionalInfo": {
"string" : "string"
},
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"resourceType": "string"
},
"reasonForNonCompliance": "string",
"reasonForNonComplianceCode": "string",
"relatedResources": [
{
"additionalInfo": {
"string" : "string"
},
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"resourceType": "string"
}
],
"severity": "string",
"taskId": "string",
"taskStartTime": number
}
],
"nextToken": "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.

findings (p. 384)

The findings (results) of the audit.

385
 AWS IoT API Reference
ListAuditFindings

Type: Array of AuditFinding (p. 801) objects

nextToken (p. 384)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

386
 AWS IoT API Reference
ListAuditMitigationActionsExecutions

ListAuditMitigationActionsExecutions
Service: AWS IoT

Gets the status of audit mitigation action tasks that were executed.

Requires permission to access the ListAuditMitigationActionsExecutions action.

Request Syntax
GET /audit/mitigationactions/executions?
actionStatus=actionStatus&findingId=findingId&maxResults=maxResults&nextToken=nextToken&taskId=taskId
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

actionStatus (p. 387)

Specify this filter to limit results to those with a specific status.

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED | SKIPPED | PENDING

findingId (p. 387)

Specify this filter to limit results to those that were applied to a specific audit finding.

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

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

Required: Yes
maxResults (p. 387)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 387)

The token for the next set of results.

taskId (p. 387)

Specify this filter to limit results to actions for a specific audit mitigation actions task.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

387
 AWS IoT API Reference
ListAuditMitigationActionsExecutions

Content-type: application/json

{
"actionsExecutions": [
{
"actionId": "string",
"actionName": "string",
"endTime": number,
"errorCode": "string",
"findingId": "string",
"message": "string",
"startTime": number,
"status": "string",
"taskId": "string"
}
],
"nextToken": "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.

actionsExecutions (p. 387)

A set of task execution results based on the input parameters. Details include the mitigation action
applied, start time, and task status.

Type: Array of AuditMitigationActionExecutionMetadata (p. 803) objects

nextToken (p. 387)

The token for the next set of results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

388
 AWS IoT API Reference
ListAuditMitigationActionsExecutions

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

389
 AWS IoT API Reference
ListAuditMitigationActionsTasks

ListAuditMitigationActionsTasks
Service: AWS IoT

Gets a list of audit mitigation action tasks that match the specified filters.

Requires permission to access the ListAuditMitigationActionsTasks action.

Request Syntax
GET /audit/mitigationactions/tasks?
auditTaskId=auditTaskId&endTime=endTime&findingId=findingId&maxResults=maxResults&nextToken=nextToken&s
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

auditTaskId (p. 390)

Specify this filter to limit results to tasks that were applied to results for a specific audit.

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

Pattern: [a-zA-Z0-9\-]+
endTime (p. 390)

Specify this filter to limit results to tasks that were completed or canceled on or before a specific
date and time.

Required: Yes
findingId (p. 390)

Specify this filter to limit results to tasks that were applied to a specific audit finding.

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

Pattern: [a-zA-Z0-9_-]+
maxResults (p. 390)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 390)

The token for the next set of results.

startTime (p. 390)

Specify this filter to limit results to tasks that began on or after a specific date and time.

Required: Yes
taskStatus (p. 390)

Specify this filter to limit results to tasks that are in a specific state.

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

390
 AWS IoT API Reference
ListAuditMitigationActionsTasks

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"tasks": [
{
"startTime": number,
"taskId": "string",
"taskStatus": "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.

nextToken (p. 391)

The token for the next set of results.

Type: String
tasks (p. 391)

The collection of audit mitigation tasks that matched the filter criteria.

Type: Array of AuditMitigationActionsTaskMetadata (p. 805) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

391
 AWS IoT API Reference
ListAuditMitigationActionsTasks

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

392
 AWS IoT API Reference
ListAuditSuppressions

ListAuditSuppressions
Service: AWS IoT

Lists your Device Defender audit listings.

Requires permission to access the ListAuditSuppressions action.

Request Syntax
POST /audit/suppressions/list HTTP/1.1
Content-type: application/json

{
"ascendingOrder": boolean,
"checkName": "string",
"maxResults": number,
"nextToken": "string",
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

ascendingOrder (p. 393)

Determines whether suppressions are listed in ascending order by expiration date or not. If
parameter isn't provided, ascendingOrder=true.

Type: Boolean

Required: No
checkName (p. 393)

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: No
maxResults (p. 393)

The maximum number of results to return at one time. The default is 25.

393
 AWS IoT API Reference
ListAuditSuppressions

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 250.

Required: No
nextToken (p. 393)

The token for the next set of results.

Type: String

Required: No
resourceIdentifier (p. 393)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"suppressions": [
{
"checkName": "string",
"description": "string",
"expirationDate": number,
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"suppressIndefinitely": boolean
}
]
}

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.

nextToken (p. 394)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

394
 AWS IoT API Reference
ListAuditSuppressions

Type: String
suppressions (p. 394)

List of audit suppressions.

Type: Array of AuditSuppression (p. 808) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

395
 AWS IoT API Reference
ListAuditTasks

ListAuditTasks
Service: AWS IoT

Lists the Device Defender audits that have been performed during a given time period.

Requires permission to access the ListAuditTasks action.

Request Syntax
GET /audit/tasks?
endTime=endTime&maxResults=maxResults&nextToken=nextToken&startTime=startTime&taskStatus=taskStatus&tas
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

endTime (p. 396)

The end of the time period.

Required: Yes
maxResults (p. 396)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 396)

The token for the next set of results.

startTime (p. 396)

The beginning of the time period. Audit information is retained for a limited time (90 days).
Requesting a start time prior to what is retained results in an "InvalidRequestException".

Required: Yes
taskStatus (p. 396)

A filter to limit the output to audits with the specified completion status: can be one of
"IN_PROGRESS", "COMPLETED", "FAILED", or "CANCELED".

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

taskType (p. 396)

A filter to limit the output to the specified type of audit: can be one of "ON_DEMAND_AUDIT_TASK"
or "SCHEDULED__AUDIT_TASK".

Valid Values: ON_DEMAND_AUDIT_TASK | SCHEDULED_AUDIT_TASK

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

396
 AWS IoT API Reference
ListAuditTasks

Content-type: application/json

{
"nextToken": "string",
"tasks": [
{
"taskId": "string",
"taskStatus": "string",
"taskType": "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.

nextToken (p. 396)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
tasks (p. 396)

The audits that were performed during the specified time period.

Type: Array of AuditTaskMetadata (p. 810) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

397
 AWS IoT API Reference
ListAuditTasks

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

398
 AWS IoT API Reference
ListAuthorizers

ListAuthorizers
Service: AWS IoT

Lists the authorizers registered in your account.

Requires permission to access the ListAuthorizers action.

Request Syntax
GET /authorizers/?
isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize&status=status HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 399)

Return the list of authorizers in ascending alphabetical order.

marker (p. 399)

A marker used to get the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 399)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

status (p. 399)

The status of the list authorizers request.

Valid Values: ACTIVE | INACTIVE

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizers": [
{
"authorizerArn": "string",
"authorizerName": "string"
}
],
"nextMarker": "string"
}

399
 AWS IoT API Reference
ListAuthorizers

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.

authorizers (p. 399)

The authorizers.

Type: Array of AuthorizerSummary (p. 815) objects

nextMarker (p. 399)

A marker used to get the next set of results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

400
 AWS IoT API Reference
ListAuthorizers

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

401
 AWS IoT API Reference
ListBillingGroups

ListBillingGroups
Service: AWS IoT

Lists the billing groups you have created.

Requires permission to access the ListBillingGroups action.

Request Syntax
GET /billing-groups?
maxResults=maxResults&namePrefixFilter=namePrefixFilter&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 402)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namePrefixFilter (p. 402)

Limit the results to billing groups whose names have the given prefix.

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

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 402)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"billingGroups": [
{
"groupArn": "string",
"groupName": "string"
}
],
"nextToken": "string"
}

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

402
 AWS IoT API Reference
ListBillingGroups

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

billingGroups (p. 402)

The list of billing groups.

Type: Array of GroupNameAndArn (p. 875) objects

nextToken (p. 402)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

403
 AWS IoT API Reference
ListCACertificates

ListCACertificates
Service: AWS IoT

Lists the CA certificates registered for your AWS account.

The results are paginated with a default page size of 25. You can use the returned marker to retrieve
additional results.

Requires permission to access the ListCACertificates action.

Request Syntax
GET /cacertificates?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 404)

Determines the order of the results.

marker (p. 404)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 404)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificates": [
{
"certificateArn": "string",
"certificateId": "string",
"creationDate": number,
"status": "string"
}
],
"nextMarker": "string"
}

404
 AWS IoT API Reference
ListCACertificates

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.

certificates (p. 404)

The CA certificates registered in your AWS account.

Type: Array of CACertificate (p. 835) objects

nextMarker (p. 404)

The current position within the list of CA certificates.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

405
 AWS IoT API Reference
ListCACertificates

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

406
 AWS IoT API Reference
ListCertificates

ListCertificates
Service: AWS IoT

Lists the certificates registered in your AWS account.

The results are paginated with a default page size of 25. You can use the returned marker to retrieve
additional results.

Requires permission to access the ListCertificates action.

Request Syntax
GET /certificates?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 407)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
marker (p. 407)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 407)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificates": [
{
"certificateArn": "string",
"certificateId": "string",
"certificateMode": "string",
"creationDate": number,
"status": "string"
}
],
"nextMarker": "string"
}

407
 AWS IoT API Reference
ListCertificates

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.

certificates (p. 407)

The descriptions of the certificates.

Type: Array of Certificate (p. 838) objects

nextMarker (p. 407)

The marker for the next set of results, or null if there are no additional results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

408
 AWS IoT API Reference
ListCertificates

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

409
 AWS IoT API Reference
ListCertificatesByCA

ListCertificatesByCA
Service: AWS IoT

List the device certificates signed by the specified CA certificate.

Requires permission to access the ListCertificatesByCA action.

Request Syntax
GET /certificates-by-ca/caCertificateId?
isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 410)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
caCertificateId (p. 410)

The ID of the CA certificate. This operation will list all registered device certificate that were signed
by this CA certificate.

Length Constraints: Fixed length of 64.

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

Required: Yes
marker (p. 410)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 410)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificates": [
{

410
 AWS IoT API Reference
ListCertificatesByCA

"certificateArn": "string",
"certificateId": "string",
"certificateMode": "string",
"creationDate": number,
"status": "string"
}
],
"nextMarker": "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.

certificates (p. 410)

The device certificates signed by the specified CA certificate.

Type: Array of Certificate (p. 838) objects

nextMarker (p. 410)

The marker for the next set of results, or null if there are no additional results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

411
 AWS IoT API Reference
ListCertificatesByCA

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

412
 AWS IoT API Reference
ListCustomMetrics

ListCustomMetrics
Service: AWS IoT

Lists your Device Defender detect custom metrics.

Requires permission to access the ListCustomMetrics action.

Request Syntax
GET /custom-metrics?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 413)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 413)

The token for the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"metricNames": [ "string" ],
"nextToken": "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.

metricNames (p. 413)

The name of the custom metric.

Type: Array of strings

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

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 413)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

413
 AWS IoT API Reference
ListCustomMetrics

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

414
 AWS IoT API Reference
ListDetectMitigationActionsExecutions

ListDetectMitigationActionsExecutions
Service: AWS IoT

Lists mitigation actions executions for a Device Defender ML Detect Security Profile.

Requires permission to access the ListDetectMitigationActionsExecutions action.

Request Syntax
GET /detect/mitigationactions/executions?
endTime=endTime&maxResults=maxResults&nextToken=nextToken&startTime=startTime&taskId=taskId&thingName=t
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

endTime (p. 415)

The end of the time period for which ML Detect mitigation actions executions are returned.
maxResults (p. 415)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 415)

The token for the next set of results.

startTime (p. 415)

A filter to limit results to those found after the specified time. You must specify either the startTime
and endTime or the taskId, but not both.
taskId (p. 415)

The unique identifier of the task.

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

Pattern: [a-zA-Z0-9_-]+
thingName (p. 415)

The name of the thing whose mitigation actions are listed.

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

violationId (p. 415)

The unique identifier of the violation.

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

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

Request Body
The request does not have a request body.

415
 AWS IoT API Reference
ListDetectMitigationActionsExecutions

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"actionsExecutions": [
{
"actionName": "string",
"errorCode": "string",
"executionEndDate": number,
"executionStartDate": number,
"message": "string",
"status": "string",
"taskId": "string",
"thingName": "string",
"violationId": "string"
}
],
"nextToken": "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.

actionsExecutions (p. 416)

List of actions executions.

Type: Array of DetectMitigationActionExecution (p. 855) objects

nextToken (p. 416)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

416
 AWS IoT API Reference
ListDetectMitigationActionsExecutions

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

417
 AWS IoT API Reference
ListDetectMitigationActionsTasks

ListDetectMitigationActionsTasks
Service: AWS IoT

List of Device Defender ML Detect mitigation actions tasks.

Requires permission to access the ListDetectMitigationActionsTasks action.

Request Syntax
GET /detect/mitigationactions/tasks?
endTime=endTime&maxResults=maxResults&nextToken=nextToken&startTime=startTime HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

endTime (p. 418)

The end of the time period for which ML Detect mitigation actions tasks are returned.

Required: Yes
maxResults (p. 418)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 418)

The token for the next set of results.

startTime (p. 418)

A filter to limit results to those found after the specified time. You must specify either the startTime
and endTime or the taskId, but not both.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"tasks": [
{
"actionsDefinition": [
{
"actionParams": {
"addThingsToThingGroupParams": {
"overrideDynamicGroups": boolean,
"thingGroupNames": [ "string" ]

418
 AWS IoT API Reference
ListDetectMitigationActionsTasks

},
"enableIoTLoggingParams": {
"logLevel": "string",
"roleArnForLogging": "string"
},
"publishFindingToSnsParams": {
"topicArn": "string"
},
"replaceDefaultPolicyVersionParams": {
"templateName": "string"
},
"updateCACertificateParams": {
"action": "string"
},
"updateDeviceCertificateParams": {
"action": "string"
}
},
"id": "string",
"name": "string",
"roleArn": "string"
}
],
"onlyActiveViolationsIncluded": boolean,
"suppressedAlertsIncluded": boolean,
"target": {
"behaviorName": "string",
"securityProfileName": "string",
"violationIds": [ "string" ]
},
"taskEndTime": number,
"taskId": "string",
"taskStartTime": number,
"taskStatistics": {
"actionsExecuted": number,
"actionsFailed": number,
"actionsSkipped": number
},
"taskStatus": "string",
"violationEventOccurrenceRange": {
"endTime": number,
"startTime": number
}
}
]
}

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.

nextToken (p. 418)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
tasks (p. 418)

The collection of ML Detect mitigation tasks that matched the filter criteria.

Type: Array of DetectMitigationActionsTaskSummary (p. 858) objects

419
 AWS IoT API Reference
ListDetectMitigationActionsTasks

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

420
 AWS IoT API Reference
ListDimensions

ListDimensions
Service: AWS IoT

List the set of dimensions that are defined for your AWS accounts.

Requires permission to access the ListDimensions action.

Request Syntax
GET /dimensions?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 421)

The maximum number of results to retrieve at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 421)

The token for the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"dimensionNames": [ "string" ],
"nextToken": "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.

dimensionNames (p. 421)

A list of the names of the defined dimensions. Use DescribeDimension to get details for a
dimension.

Type: Array of strings

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

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

421
 AWS IoT API Reference
ListDimensions

nextToken (p. 421)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

422
 AWS IoT API Reference
ListDomainConfigurations

ListDomainConfigurations
Service: AWS IoT

Gets a list of domain configurations for the user. This list is sorted alphabetically by domain
configuration name.

Requires permission to access the ListDomainConfigurations action.

Request Syntax
GET /domainConfigurations?marker=marker&pageSize=pageSize&serviceType=serviceType HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

marker (p. 423)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 423)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

serviceType (p. 423)

The type of service delivered by the endpoint.

Valid Values: DATA | CREDENTIAL_PROVIDER | JOBS

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"domainConfigurations": [
{
"domainConfigurationArn": "string",
"domainConfigurationName": "string",
"serviceType": "string"
}
],
"nextMarker": "string"
}

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

423
 AWS IoT API Reference
ListDomainConfigurations

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

domainConfigurations (p. 423)

A list of objects that contain summary information about the user's domain configurations.

Type: Array of DomainConfigurationSummary (p. 861) objects

nextMarker (p. 423)

The marker for the next set of results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

424
 AWS IoT API Reference
ListDomainConfigurations

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

425
 AWS IoT API Reference
ListFleetMetrics

ListFleetMetrics
Service: AWS IoT

Lists all your fleet metrics.

Requires permission to access the ListFleetMetrics action.

Request Syntax
GET /fleet-metrics?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 426)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 426)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null
to receive the first set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"fleetMetrics": [
{
"metricArn": "string",
"metricName": "string"
}
],
"nextToken": "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.

fleetMetrics (p. 426)

The list of fleet metrics objects.

Type: Array of FleetMetricNameAndArn (p. 874) objects

426
 AWS IoT API Reference
ListFleetMetrics

nextToken (p. 426)

The token for the next set of results. Will not be returned if the operation has returned all results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

427
 AWS IoT API Reference
ListIndices

ListIndices
Service: AWS IoT

Lists the search indices.

Requires permission to access the ListIndices action.

Request Syntax
GET /indices?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 428)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 500.

nextToken (p. 428)

The token used to get the next set of results, or null if there are no additional results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"indexNames": [ "string" ],
"nextToken": "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.

indexNames (p. 428)

The index names.

Type: Array of strings

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

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 428)

The token used to get the next set of results, or null if there are no additional results.

428
 AWS IoT API Reference
ListIndices

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

429
 AWS IoT API Reference
ListJobExecutionsForJob

ListJobExecutionsForJob
Service: AWS IoT

Lists the job executions for a job.

Requires permission to access the ListJobExecutionsForJob action.

Request Syntax
GET /jobs/jobId/things?maxResults=maxResults&nextToken=nextToken&status=status HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 430)

The unique identifier you assigned to this job when it was created.

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

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

Required: Yes
maxResults (p. 430)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 430)

The token to retrieve the next set of results.

status (p. 430)

The status of the job.

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"executionSummaries": [
{
"jobExecutionSummary": {
"executionNumber": number,
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,

430
 AWS IoT API Reference
ListJobExecutionsForJob

"status": "string"
},
"thingArn": "string"
}
],
"nextToken": "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.

executionSummaries (p. 430)

A list of job execution summaries.

Type: Array of JobExecutionSummaryForJob (p. 899) objects

nextToken (p. 430)

The token for the next set of results, or null if there are no additional results.

Type: String

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

431
 AWS IoT API Reference
ListJobExecutionsForJob

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

432
 AWS IoT API Reference
ListJobExecutionsForThing

ListJobExecutionsForThing
Service: AWS IoT

Lists the job executions for the specified thing.

Requires permission to access the ListJobExecutionsForThing action.

Request Syntax
GET /things/thingName/jobs?
maxResults=maxResults&namespaceId=namespaceId&nextToken=nextToken&status=status HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 433)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namespaceId (p. 433)

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 notifications 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.

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

Pattern: [a-zA-Z0-9_-]+
nextToken (p. 433)

The token to retrieve the next set of results.

status (p. 433)

An optional filter that lets you search for jobs that have the specified status.

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED
thingName (p. 433)

The thing name.

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

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

Required: Yes

Request Body
The request does not have a request body.

433
 AWS IoT API Reference
ListJobExecutionsForThing

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"executionSummaries": [
{
"jobExecutionSummary": {
"executionNumber": number,
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,
"status": "string"
},
"jobId": "string"
}
],
"nextToken": "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.

executionSummaries (p. 434)

A list of job execution summaries.

Type: Array of JobExecutionSummaryForThing (p. 900) objects

nextToken (p. 434)

The token for the next set of results, or null if there are no additional results.

Type: String

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

434
 AWS IoT API Reference
ListJobExecutionsForThing

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

435
 AWS IoT API Reference
ListJobs

ListJobs
Service: AWS IoT

Lists jobs.

Requires permission to access the ListJobs action.

Request Syntax
GET /jobs?
maxResults=maxResults&namespaceId=namespaceId&nextToken=nextToken&status=status&targetSelection=targetS
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 436)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namespaceId (p. 436)

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 notifications 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.

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

Pattern: [a-zA-Z0-9_-]+
nextToken (p. 436)

The token to retrieve the next set of results.

status (p. 436)

An optional filter that lets you search for jobs that have the specified status.

Valid Values: IN_PROGRESS | CANCELED | COMPLETED | DELETION_IN_PROGRESS

targetSelection (p. 436)

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those
things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be
run on a thing when a change is detected in a target. For example, a job will run on a thing when
the thing is added to a target group, even after the job was completed by all things originally in the
group.

Valid Values: CONTINUOUS | SNAPSHOT

thingGroupId (p. 436)

A filter that limits the returned jobs to those for the specified group.

436
 AWS IoT API Reference
ListJobs

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

Pattern: [a-zA-Z0-9\-]+
thingGroupName (p. 436)

A filter that limits the returned jobs to those for the specified group.

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

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

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"jobs": [
{
"completedAt": number,
"createdAt": number,
"jobArn": "string",
"jobId": "string",
"lastUpdatedAt": number,
"status": "string",
"targetSelection": "string",
"thingGroupId": "string"
}
],
"nextToken": "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.

jobs (p. 437)

A list of jobs.

Type: Array of JobSummary (p. 903) objects

nextToken (p. 437)

The token for the next set of results, or null if there are no additional results.

Type: String

Errors
InvalidRequestException

The request is not valid.

437
 AWS IoT API Reference
ListJobs

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

438
 AWS IoT API Reference
ListJobTemplates

ListJobTemplates
Service: AWS IoT

Returns a list of job templates.

Requires permission to access the ListJobTemplates action.

Request Syntax
GET /job-templates?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 439)

The maximum number of results to return in the list.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 439)

The token to use to return the next set of results in the list.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"jobTemplates": [
{
"createdAt": number,
"description": "string",
"jobTemplateArn": "string",
"jobTemplateId": "string"
}
],
"nextToken": "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.

jobTemplates (p. 439)

A list of objects that contain information about the job templates.

Type: Array of JobTemplateSummary (p. 905) objects

439
 AWS IoT API Reference
ListJobTemplates

nextToken (p. 439)

The token for the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

440
 AWS IoT API Reference
ListMitigationActions

ListMitigationActions
Service: AWS IoT

Gets a list of all mitigation actions that match the specified filter criteria.

Requires permission to access the ListMitigationActions action.

Request Syntax
GET /mitigationactions/actions?
actionType=actionType&maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

actionType (p. 441)

Specify a value to limit the result to mitigation actions with a specific action type.

Valid Values: UPDATE_DEVICE_CERTIFICATE | UPDATE_CA_CERTIFICATE |

ADD_THINGS_TO_THING_GROUP | REPLACE_DEFAULT_POLICY_VERSION |
ENABLE_IOT_LOGGING | PUBLISH_FINDING_TO_SNS
maxResults (p. 441)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 441)

The token for the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"actionIdentifiers": [
{
"actionArn": "string",
"actionName": "string",
"creationDate": number
}
],
"nextToken": "string"
}

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

441
 AWS IoT API Reference
ListMitigationActions

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

actionIdentifiers (p. 441)

A set of actions that matched the specified filter criteria.

Type: Array of MitigationActionIdentifier (p. 920) objects

nextToken (p. 441)

The token for the next set of results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

442
 AWS IoT API Reference
ListOTAUpdates

ListOTAUpdates
Service: AWS IoT

Lists OTA updates.

Requires permission to access the ListOTAUpdates action.

Request Syntax
GET /otaUpdates?maxResults=maxResults&nextToken=nextToken&otaUpdateStatus=otaUpdateStatus
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 443)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 443)

A token used to retrieve the next set of results.

otaUpdateStatus (p. 443)

The OTA update job status.

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"otaUpdates": [
{
"creationDate": number,
"otaUpdateArn": "string",
"otaUpdateId": "string"
}
]
}

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

443
 AWS IoT API Reference
ListOTAUpdates

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

nextToken (p. 443)

A token to use to get the next set of results.

Type: String
otaUpdates (p. 443)

A list of OTA update jobs.

Type: Array of OTAUpdateSummary (p. 930) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

444
AWS IoT API Reference
ListOTAUpdates

445
 AWS IoT API Reference
ListOutgoingCertificates

ListOutgoingCertificates
Service: AWS IoT

Lists certificates that are being transferred but not yet accepted.

Requires permission to access the ListOutgoingCertificates action.

Request Syntax
GET /certificates-out-going?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 446)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
marker (p. 446)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 446)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",
"outgoingCertificates": [
{
"certificateArn": "string",
"certificateId": "string",
"creationDate": number,
"transferDate": number,
"transferMessage": "string",
"transferredTo": "string"
}
]
}

446
 AWS IoT API Reference
ListOutgoingCertificates

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.

nextMarker (p. 446)

The marker for the next set of results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
outgoingCertificates (p. 446)

The certificates that are being transferred but not yet accepted.

Type: Array of OutgoingCertificate (p. 931) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

447
 AWS IoT API Reference
ListOutgoingCertificates

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

448
 AWS IoT API Reference
ListPolicies

ListPolicies
Service: AWS IoT

Lists your policies.

Requires permission to access the ListPolicies action.

Request Syntax
GET /policies?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 449)

Specifies the order for results. If true, the results are returned in ascending creation order.
marker (p. 449)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 449)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",
"policies": [
{
"policyArn": "string",
"policyName": "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.

449
 AWS IoT API Reference
ListPolicies

nextMarker (p. 449)

The marker for the next set of results, or null if there are no additional results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
policies (p. 449)

The descriptions of the policies.

Type: Array of Policy (p. 934) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

450
 AWS IoT API Reference
ListPolicies

• AWS SDK for Ruby V3

451
 AWS IoT API Reference
ListPolicyPrincipals

ListPolicyPrincipals
Service: AWS IoT

Lists the principals associated with the specified policy.

Note: This action is deprecated. Please use ListTargetsForPolicy (p. 483) instead.

Requires permission to access the ListPolicyPrincipals action.

Request Syntax
GET /policy-principals?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize
HTTP/1.1
x-amzn-iot-policy: policyName

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 452)

Specifies the order for results. If true, the results are returned in ascending creation order.
marker (p. 452)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 452)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

policyName (p. 452)

The policy name.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",

452
 AWS IoT API Reference
ListPolicyPrincipals

"principals": [ "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.

nextMarker (p. 452)

The marker for the next set of results, or null if there are no additional results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
principals (p. 452)

The descriptions of the principals.

Type: Array of strings

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

453
 AWS IoT API Reference
ListPolicyPrincipals

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

454
 AWS IoT API Reference
ListPolicyVersions

ListPolicyVersions
Service: AWS IoT

Lists the versions of the specified policy and identifies the default version.

Requires permission to access the ListPolicyVersions action.

Request Syntax
GET /policies/policyName/version HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 455)

The policy name.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"policyVersions": [
{
"createDate": number,
"isDefaultVersion": boolean,
"versionId": "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.

policyVersions (p. 455)

The policy versions.

Type: Array of PolicyVersion (p. 935) objects

455
 AWS IoT API Reference
ListPolicyVersions

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

456
 AWS IoT API Reference
ListPrincipalPolicies

ListPrincipalPolicies
Service: AWS IoT

Lists the policies attached to the specified principal. If you use an Cognito identity, the ID must be in
AmazonCognito Identity format.

Note: This action is deprecated. Please use ListAttachedPolicies (p. 380) instead.

Requires permission to access the ListPrincipalPolicies action.

Request Syntax
GET /principal-policies?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize
HTTP/1.1
x-amzn-iot-principal: principal

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 457)

Specifies the order for results. If true, results are returned in ascending creation order.
marker (p. 457)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 457)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

principal (p. 457)

The principal. Valid principals are CertificateArn (arn:aws:iot:region:accountId:cert/certificateId),

thingGroupArn (arn:aws:iot:region:accountId:thinggroup/groupName) and CognitoId (region:id).

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",
"policies": [
{
"policyArn": "string",

457
 AWS IoT API Reference
ListPrincipalPolicies

"policyName": "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.

nextMarker (p. 457)

The marker for the next set of results, or null if there are no additional results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
policies (p. 457)

The policies.

Type: Array of Policy (p. 934) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

458
 AWS IoT API Reference
ListPrincipalPolicies

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

459
 AWS IoT API Reference
ListPrincipalThings

ListPrincipalThings
Service: AWS IoT

Lists the things associated with the specified principal. A principal can be X.509 certificates, IAM users,
groups, and roles, Amazon Cognito identities or federated identities.

Requires permission to access the ListPrincipalThings action.

Request Syntax
GET /principals/things?maxResults=maxResults&nextToken=nextToken HTTP/1.1
x-amzn-principal: principal

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 460)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 460)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
principal (p. 460)

The principal.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"things": [ "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.

nextToken (p. 460)

The token to use to get the next set of results, or null if there are no additional results.

460
 AWS IoT API Reference
ListPrincipalThings

Type: String
things (p. 460)

The things.

Type: Array of strings

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

461
 AWS IoT API Reference
ListPrincipalThings

• AWS SDK for Python

• AWS SDK for Ruby V3

462
 AWS IoT API Reference
ListProvisioningTemplates

ListProvisioningTemplates
Service: AWS IoT

Lists the fleet provisioning templates in your AWS account.

Requires permission to access the ListProvisioningTemplates action.

Request Syntax
GET /provisioning-templates?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 463)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 463)

A token to retrieve the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"templates": [
{
"creationDate": number,
"description": "string",
"enabled": boolean,
"lastModifiedDate": number,
"templateArn": "string",
"templateName": "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.

nextToken (p. 463)

A token to retrieve the next set of results.

463
 AWS IoT API Reference
ListProvisioningTemplates

Type: String
templates (p. 463)

A list of fleet provisioning templates

Type: Array of ProvisioningTemplateSummary (p. 939) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

464
 AWS IoT API Reference
ListProvisioningTemplateVersions

ListProvisioningTemplateVersions
Service: AWS IoT

A list of fleet provisioning template versions.

Requires permission to access the ListProvisioningTemplateVersions action.

Request Syntax
GET /provisioning-templates/templateName/versions?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 465)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 465)

A token to retrieve the next set of results.

templateName (p. 465)

The name of the fleet provisioning template.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"versions": [
{
"creationDate": number,
"isDefaultVersion": boolean,
"versionId": number
}
]
}

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

465
 AWS IoT API Reference
ListProvisioningTemplateVersions

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

nextToken (p. 465)

A token to retrieve the next set of results.

Type: String
versions (p. 465)

The list of fleet provisioning template versions.

Type: Array of ProvisioningTemplateVersionSummary (p. 941) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

466
 AWS IoT API Reference
ListProvisioningTemplateVersions

467
 AWS IoT API Reference
ListRoleAliases

ListRoleAliases
Service: AWS IoT

Lists the role aliases registered in your account.

Requires permission to access the ListRoleAliases action.

Request Syntax
GET /role-aliases?isAscendingOrder=ascendingOrder&marker=marker&pageSize=pageSize HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 468)

Return the list of role aliases in ascending alphabetical order.

marker (p. 468)

A marker used to get the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 468)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",
"roleAliases": [ "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.

nextMarker (p. 468)

A marker used to get the next set of results.

468
 AWS IoT API Reference
ListRoleAliases

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
roleAliases (p. 468)

The role aliases.

Type: Array of strings

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

Pattern: [\w=,@-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

469
 AWS IoT API Reference
ListRoleAliases

• AWS SDK for Ruby V3

470
 AWS IoT API Reference
ListScheduledAudits

ListScheduledAudits
Service: AWS IoT

Lists all of your scheduled audits.

Requires permission to access the ListScheduledAudits action.

Request Syntax
GET /audit/scheduledaudits?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 471)

The maximum number of results to return at one time. The default is 25.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 471)

The token for the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"scheduledAudits": [
{
"dayOfMonth": "string",
"dayOfWeek": "string",
"frequency": "string",
"scheduledAuditArn": "string",
"scheduledAuditName": "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.

nextToken (p. 471)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

471
 AWS IoT API Reference
ListScheduledAudits

Type: String
scheduledAudits (p. 471)

The list of scheduled audits.

Type: Array of ScheduledAuditMetadata (p. 959) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

472
 AWS IoT API Reference
ListSecurityProfiles

ListSecurityProfiles
Service: AWS IoT

Lists the Device Defender security profiles you've created. You can filter security profiles by dimension or
custom metric.

Requires permission to access the ListSecurityProfiles action.

Note
dimensionName and metricName cannot be used in the same request.

Request Syntax
GET /security-profiles?
dimensionName=dimensionName&maxResults=maxResults&metricName=metricName&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

dimensionName (p. 473)

A filter to limit results to the security profiles that use the defined dimension. Cannot be used with
metricName

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

Pattern: [a-zA-Z0-9:_-]+
maxResults (p. 473)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

metricName (p. 473)

The name of the custom metric. Cannot be used with dimensionName.

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

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 473)

The token for the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",

473
 AWS IoT API Reference
ListSecurityProfiles

"securityProfileIdentifiers": [
{
"arn": "string",
"name": "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.

nextToken (p. 473)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
securityProfileIdentifiers (p. 473)

A list of security profile identifiers (names and ARNs).

Type: Array of SecurityProfileIdentifier (p. 961) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

474
 AWS IoT API Reference
ListSecurityProfiles

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

475
 AWS IoT API Reference
ListSecurityProfilesForTarget

ListSecurityProfilesForTarget
Service: AWS IoT

Lists the Device Defender security profiles attached to a target (thing group).

Requires permission to access the ListSecurityProfilesForTarget action.

Request Syntax
GET /security-profiles-for-target?
maxResults=maxResults&nextToken=nextToken&recursive=recursive&securityProfileTargetArn=securityProfileT
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 476)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 476)

The token for the next set of results.

recursive (p. 476)

If true, return child groups too.

securityProfileTargetArn (p. 476)

The ARN of the target (thing group) whose attached security profiles you want to get.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"securityProfileTargetMappings": [
{
"securityProfileIdentifier": {
"arn": "string",
"name": "string"
},
"target": {
"arn": "string"
}
}
]

476
 AWS IoT API Reference
ListSecurityProfilesForTarget

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.

nextToken (p. 476)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
securityProfileTargetMappings (p. 476)

A list of security profiles and their associated targets.

Type: Array of SecurityProfileTargetMapping (p. 963) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

477
 AWS IoT API Reference
ListSecurityProfilesForTarget

• AWS SDK for Ruby V3

478
 AWS IoT API Reference
ListStreams

ListStreams
Service: AWS IoT

Lists all of the streams in your AWS account.

Requires permission to access the ListStreams action.

Request Syntax
GET /streams?isAscendingOrder=ascendingOrder&maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 479)

Set to true to return the list of streams in ascending order.

maxResults (p. 479)

The maximum number of results to return at a time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 479)

A token used to get the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"streams": [
{
"description": "string",
"streamArn": "string",
"streamId": "string",
"streamVersion": number
}
]
}

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.

479
 AWS IoT API Reference
ListStreams

nextToken (p. 479)

A token used to get the next set of results.

Type: String
streams (p. 479)

A list of streams.

Type: Array of StreamSummary (p. 978) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

480
 AWS IoT API Reference
ListTagsForResource

ListTagsForResource
Service: AWS IoT

Lists the tags (metadata) you have assigned to the resource.

Requires permission to access the ListTagsForResource action.

Request Syntax
GET /tags?nextToken=nextToken&resourceArn=resourceArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

nextToken (p. 481)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
resourceArn (p. 481)

The ARN of the resource.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"tags": [
{
"Key": "string",
"Value": "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.

nextToken (p. 481)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

481
 AWS IoT API Reference
ListTagsForResource

tags (p. 481)

The list of tags assigned to the resource.

Type: Array of Tag (p. 979) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

482
 AWS IoT API Reference
ListTargetsForPolicy

ListTargetsForPolicy
Service: AWS IoT

List targets for the specified policy.

Requires permission to access the ListTargetsForPolicy action.

Request Syntax
POST /policy-targets/policyName?marker=marker&pageSize=pageSize HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

marker (p. 483)

A marker used to get the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 483)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

policyName (p. 483)

The policy name.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextMarker": "string",
"targets": [ "string" ]
}

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

483
 AWS IoT API Reference
ListTargetsForPolicy

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

nextMarker (p. 483)

A marker used to get the next set of results.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
targets (p. 483)

The policy targets.

Type: Array of strings

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

484
 AWS IoT API Reference
ListTargetsForPolicy

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

485
 AWS IoT API Reference
ListTargetsForSecurityProfile

ListTargetsForSecurityProfile
Service: AWS IoT

Lists the targets (thing groups) associated with a given Device Defender security profile.

Requires permission to access the ListTargetsForSecurityProfile action.

Request Syntax
GET /security-profiles/securityProfileName/targets?
maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 486)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 486)

The token for the next set of results.

securityProfileName (p. 486)

The security profile.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"securityProfileTargets": [
{
"arn": "string"
}
]
}

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

486
 AWS IoT API Reference
ListTargetsForSecurityProfile

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

nextToken (p. 486)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
securityProfileTargets (p. 486)

The thing groups to which the security profile is attached.

Type: Array of SecurityProfileTarget (p. 962) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

487
 AWS IoT API Reference
ListThingGroups

ListThingGroups
Service: AWS IoT

List the thing groups in your account.

Requires permission to access the ListThingGroups action.

Request Syntax
GET /thing-groups?
maxResults=maxResults&namePrefixFilter=namePrefixFilter&nextToken=nextToken&parentGroup=parentGroup&rec
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 488)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

namePrefixFilter (p. 488)

A filter that limits the results to those with the specified name prefix.

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

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 488)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
parentGroup (p. 488)

A filter that limits the results to those with the specified parent group.

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

Pattern: [a-zA-Z0-9:_-]+
recursive (p. 488)

If true, return child groups as well.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",

488
 AWS IoT API Reference
ListThingGroups

"thingGroups": [
{
"groupArn": "string",
"groupName": "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.

nextToken (p. 488)

The token to use to get the next set of results. Will not be returned if operation has returned all
results.

Type: String
thingGroups (p. 488)

The thing groups.

Type: Array of GroupNameAndArn (p. 875) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

489
 AWS IoT API Reference
ListThingGroups

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

490
 AWS IoT API Reference
ListThingGroupsForThing

ListThingGroupsForThing
Service: AWS IoT

List the thing groups to which the specified thing belongs.

Requires permission to access the ListThingGroupsForThing action.

Request Syntax
GET /things/thingName/thing-groups?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 491)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 491)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
thingName (p. 491)

The thing name.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"thingGroups": [
{
"groupArn": "string",
"groupName": "string"
}
]
}

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

491
 AWS IoT API Reference
ListThingGroupsForThing

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

nextToken (p. 491)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
thingGroups (p. 491)

The thing groups.

Type: Array of GroupNameAndArn (p. 875) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

492
 AWS IoT API Reference
ListThingPrincipals

ListThingPrincipals
Service: AWS IoT

Lists the principals associated with 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 ListThingPrincipals action.

Request Syntax
GET /things/thingName/principals?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 493)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 493)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
thingName (p. 493)

The name of the thing.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"principals": [ "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.

493
 AWS IoT API Reference
ListThingPrincipals

nextToken (p. 493)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
principals (p. 493)

The principals associated with the thing.

Type: Array of strings

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

494
 AWS IoT API Reference
ListThingPrincipals

• AWS SDK for Python

• AWS SDK for Ruby V3

495
 AWS IoT API Reference
ListThingRegistrationTaskReports

ListThingRegistrationTaskReports
Service: AWS IoT

Information about the thing registration tasks.

Request Syntax
GET /thing-registration-tasks/taskId/reports?
maxResults=maxResults&nextToken=nextToken&reportType=reportType HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 496)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 496)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
reportType (p. 496)

The type of task report.

Valid Values: ERRORS | RESULTS

Required: Yes
taskId (p. 496)

The id of the task.

Length Constraints: Maximum length of 40.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"reportType": "string",
"resourceLinks": [ "string" ]
}

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

496
 AWS IoT API Reference
ListThingRegistrationTaskReports

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

nextToken (p. 496)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
reportType (p. 496)

The type of task report.

Type: String

Valid Values: ERRORS | RESULTS

resourceLinks (p. 496)

Links to the task resources.

Type: Array of strings

Length Constraints: Maximum length of 65535.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

497
 AWS IoT API Reference
ListThingRegistrationTaskReports

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

498
 AWS IoT API Reference
ListThingRegistrationTasks

ListThingRegistrationTasks
Service: AWS IoT

List bulk thing provisioning tasks.

Requires permission to access the ListThingRegistrationTasks action.

Request Syntax
GET /thing-registration-tasks?maxResults=maxResults&nextToken=nextToken&status=status
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 499)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 499)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
status (p. 499)

The status of the bulk thing provisioning task.

Valid Values: InProgress | Completed | Failed | Cancelled | Cancelling

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"taskIds": [ "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.

nextToken (p. 499)

The token to use to get the next set of results, or null if there are no additional results.

499
 AWS IoT API Reference
ListThingRegistrationTasks

Type: String
taskIds (p. 499)

A list of bulk thing provisioning task IDs.

Type: Array of strings

Length Constraints: Maximum length of 40.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

500
 AWS IoT API Reference
ListThings

ListThings
Service: AWS IoT

Lists your things. Use the attributeName and attributeValue parameters to filter your things. For
example, calling ListThings with attributeName=Color and attributeValue=Red retrieves all things in
the registry that contain an attribute Color with the value Red.

Requires permission to access the ListThings action.

Note
You will not be charged for calling this API if an Access denied error is returned. You will also
not be charged if no attributes or pagination token was provided in request and no pagination
token and no results were returned.

Request Syntax
GET /things?
attributeName=attributeName&attributeValue=attributeValue&maxResults=maxResults&nextToken=nextToken&thi
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

attributeName (p. 501)

The attribute name used to search for things.

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_.,@/:#-]+
attributeValue (p. 501)

The attribute value used to search for things.

Length Constraints: Maximum length of 800.

Pattern: [a-zA-Z0-9_.,@/:#-]*
maxResults (p. 501)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 501)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
thingTypeName (p. 501)

The name of the thing type used to search for things.

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

Pattern: [a-zA-Z0-9:_-]+
usePrefixAttributeValue (p. 501)

When true, the action returns the thing resources with attribute values that start with the
attributeValue provided.

501
 AWS IoT API Reference
ListThings

When false, or not present, the action returns only the thing resources with attribute values that
match the entire attributeValue provided.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"things": [
{
"attributes": {
"string" : "string"
},
"thingArn": "string",
"thingName": "string",
"thingTypeName": "string",
"version": number
}
]
}

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.

nextToken (p. 502)

The token to use to get the next set of results. Will not be returned if operation has returned all
results.

Type: String
things (p. 502)

The things.

Type: Array of ThingAttribute (p. 984) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

502
 AWS IoT API Reference
ListThings

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

503
 AWS IoT API Reference
ListThingsInBillingGroup

ListThingsInBillingGroup
Service: AWS IoT

Lists the things you have added to the given billing group.

Requires permission to access the ListThingsInBillingGroup action.

Request Syntax
GET /billing-groups/billingGroupName/things?maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

billingGroupName (p. 504)

The name of the billing group.

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

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

Required: Yes
maxResults (p. 504)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 504)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"things": [ "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.

504
 AWS IoT API Reference
ListThingsInBillingGroup

nextToken (p. 504)

The token to use to get the next set of results. Will not be returned if operation has returned all
results.

Type: String
things (p. 504)

A list of things in the billing group.

Type: Array of strings

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

505
 AWS IoT API Reference
ListThingsInThingGroup

ListThingsInThingGroup
Service: AWS IoT

Lists the things in the specified group.

Requires permission to access the ListThingsInThingGroup action.

Request Syntax
GET /thing-groups/thingGroupName/things?
maxResults=maxResults&nextToken=nextToken&recursive=recursive HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 506)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 506)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
recursive (p. 506)

When true, list things in this thing group and in all child groups as well.
thingGroupName (p. 506)

The thing group name.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"things": [ "string" ]
}

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

506
 AWS IoT API Reference
ListThingsInThingGroup

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

nextToken (p. 506)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
things (p. 506)

The things in the specified thing group.

Type: Array of strings

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

507
 AWS IoT API Reference
ListThingTypes

ListThingTypes
Service: AWS IoT

Lists the existing thing types.

Requires permission to access the ListThingTypes action.

Request Syntax
GET /thing-types?maxResults=maxResults&nextToken=nextToken&thingTypeName=thingTypeName
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 508)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 508)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
thingTypeName (p. 508)

The name of the thing type.

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

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

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"thingTypes": [
{
"thingTypeArn": "string",
"thingTypeMetadata": {
"creationDate": number,
"deprecated": boolean,
"deprecationDate": number
},
"thingTypeName": "string",
"thingTypeProperties": {
"searchableAttributes": [ "string" ],
"thingTypeDescription": "string"

508
 AWS IoT API Reference
ListThingTypes

}
}
]
}

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.

nextToken (p. 508)

The token for the next set of results. Will not be returned if operation has returned all results.

Type: String
thingTypes (p. 508)

The thing types.

Type: Array of ThingTypeDefinition (p. 996) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

509
 AWS IoT API Reference
ListThingTypes

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

510
 AWS IoT API Reference
ListTopicRuleDestinations

ListTopicRuleDestinations
Service: AWS IoT

Lists all the topic rule destinations in your AWS account.

Requires permission to access the ListTopicRuleDestinations action.

Request Syntax
GET /destinations?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 511)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 1000.

nextToken (p. 511)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"destinationSummaries": [
{
"arn": "string",
"createdAt": number,
"httpUrlSummary": {
"confirmationUrl": "string"
},
"lastUpdatedAt": number,
"status": "string",
"statusReason": "string",
"vpcDestinationSummary": {
"roleArn": "string",
"securityGroups": [ "string" ],
"subnetIds": [ "string" ],
"vpcId": "string"
}
}
],
"nextToken": "string"
}

511
 AWS IoT API Reference
ListTopicRuleDestinations

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.

destinationSummaries (p. 511)

Information about a topic rule destination.

Type: Array of TopicRuleDestinationSummary (p. 1010) objects

nextToken (p. 511)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

512
 AWS IoT API Reference
ListTopicRules

ListTopicRules
Service: AWS IoT

Lists the rules for the specific topic.

Requires permission to access the ListTopicRules action.

Request Syntax
GET /rules?maxResults=maxResults&nextToken=nextToken&ruleDisabled=ruleDisabled&topic=topic
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 513)

The maximum number of results to return.

Valid Range: Minimum value of 1. Maximum value of 10000.

nextToken (p. 513)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
ruleDisabled (p. 513)

Specifies whether the rule is disabled.

topic (p. 513)

The topic.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"rules": [
{
"createdAt": number,
"ruleArn": "string",
"ruleDisabled": boolean,
"ruleName": "string",
"topicPattern": "string"
}
]
}

513
 AWS IoT API Reference
ListTopicRules

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.

nextToken (p. 513)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
rules (p. 513)

The rules.

Type: Array of TopicRuleListItem (p. 1012) objects

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

514
 AWS IoT API Reference
ListV2LoggingLevels

ListV2LoggingLevels
Service: AWS IoT

Lists logging levels.

Requires permission to access the ListV2LoggingLevels action.

Request Syntax
GET /v2LoggingLevel?maxResults=maxResults&nextToken=nextToken&targetType=targetType
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 515)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 515)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
targetType (p. 515)

The type of resource for which you are configuring logging. Must be THING_Group.

Valid Values: DEFAULT | THING_GROUP

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"logTargetConfigurations": [
{
"logLevel": "string",
"logTarget": {
"targetName": "string",
"targetType": "string"
}
}
],
"nextToken": "string"
}

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

515
 AWS IoT API Reference
ListV2LoggingLevels

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

logTargetConfigurations (p. 515)

The logging configuration for a target.

Type: Array of LogTargetConfiguration (p. 913) objects

nextToken (p. 515)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

NotConfiguredException

The resource is not configured.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

516
 AWS IoT API Reference
ListViolationEvents

ListViolationEvents
Service: AWS IoT

Lists the Device Defender security profile violations discovered during the given time period. You can
use filters to limit the results to those alerts issued for a particular security profile, behavior, or thing
(device).

Requires permission to access the ListViolationEvents action.

Request Syntax
GET /violation-events?
behaviorCriteriaType=behaviorCriteriaType&endTime=endTime&listSuppressedAlerts=listSuppressedAlerts&max
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

behaviorCriteriaType (p. 517)

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

endTime (p. 517)

The end time for the alerts to be listed.

Required: Yes
listSuppressedAlerts (p. 517)

A list of all suppressed alerts.

maxResults (p. 517)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 517)

The token for the next set of results.

securityProfileName (p. 517)

A filter to limit results to those alerts generated by the specified security profile.

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

Pattern: [a-zA-Z0-9:_-]+
startTime (p. 517)

The start time for the alerts to be listed.

Required: Yes
thingName (p. 517)

A filter to limit results to those alerts caused by the specified thing.

517
 AWS IoT API Reference
ListViolationEvents

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

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"violationEvents": [
{
"behavior": {
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
},
"metricValue": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
},
"securityProfileName": "string",
"thingName": "string",
"violationEventAdditionalInfo": {
"confidenceLevel": "string"
},
"violationEventTime": number,
"violationEventType": "string",
"violationId": "string"
}
]

518
 AWS IoT API Reference
ListViolationEvents

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.

nextToken (p. 518)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
violationEvents (p. 518)

The security profile violation alerts issued for this account during the given time period, potentially
filtered by security profile, behavior violated, or thing (device) violating.

Type: Array of ViolationEvent (p. 1019) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

519
 AWS IoT API Reference
RegisterCACertificate

RegisterCACertificate
Service: AWS IoT

Registers a CA certificate with AWS IoT. This CA certificate can then be used to sign device certificates,
which can be then registered with AWS IoT. You can register up to 10 CA certificates per AWS account
that have the same subject field. This enables you to have up to 10 certificate authorities sign your
device certificates. If you have more than one CA certificate registered, make sure you pass the CA
certificate when you register your device certificates with the RegisterCertificate (p. 524) action.

Requires permission to access the RegisterCACertificate action.

Request Syntax
POST /cacertificate?allowAutoRegistration=allowAutoRegistration&setAsActive=setAsActive
HTTP/1.1
Content-type: application/json

{
"caCertificate": "string",
"registrationConfig": {
"roleArn": "string",
"templateBody": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"verificationCertificate": "string"
}

URI Request Parameters

The request uses the following URI parameters.

allowAutoRegistration (p. 520)

Allows this CA certificate to be used for auto registration of device certificates.

setAsActive (p. 520)

A boolean value that specifies if the CA certificate is set to active.

Request Body
The request accepts the following data in JSON format.

caCertificate (p. 520)

The CA certificate.

Type: String

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

Required: Yes

520
 AWS IoT API Reference
RegisterCACertificate

registrationConfig (p. 520)

Information about the registration configuration.

Type: RegistrationConfig (p. 947) object

Required: No
tags (p. 520)

Metadata which can be used to manage the CA certificate.

Note
For URI Request parameters use format: ...key1=value1&key2=value2...
For the CLI command-line parameter use format: &&tags "key1=value1&key2=value2..."
For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

Type: Array of Tag (p. 979) objects

Required: No
verificationCertificate (p. 520)

The private key verification certificate.

Type: String

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

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateArn": "string",
"certificateId": "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.

certificateArn (p. 521)

The CA certificate ARN.

Type: String
certificateId (p. 521)

The CA certificate identifier.

Type: String

Length Constraints: Fixed length of 64.

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

521
 AWS IoT API Reference
RegisterCACertificate

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

RegistrationCodeValidationException

The registration code is invalid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

522
 AWS IoT API Reference
RegisterCACertificate

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

523
 AWS IoT API Reference
RegisterCertificate

RegisterCertificate
Service: AWS IoT

Registers a device certificate with AWS IoT. If you have more than one CA certificate that has the same
subject field, you must specify the CA certificate that was used to sign the device certificate being
registered.

Requires permission to access the RegisterCertificate action.

Request Syntax
POST /certificate/register?setAsActive=setAsActive HTTP/1.1
Content-type: application/json

{
"caCertificatePem": "string",
"certificatePem": "string",
"status": "string"
}

URI Request Parameters

The request uses the following URI parameters.

setAsActive (p. 524)

This parameter has been deprecated.

A boolean value that specifies if the certificate is set to active.

Request Body
The request accepts the following data in JSON format.

caCertificatePem (p. 524)

The CA certificate used to sign the device certificate being registered.

Type: String

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

Required: No
certificatePem (p. 524)

The certificate data, in PEM format.

Type: String

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

Required: Yes
status (p. 524)

The status of the register certificate request.

Type: String

524
 AWS IoT API Reference
RegisterCertificate

Valid Values: ACTIVE | INACTIVE | REVOKED | PENDING_TRANSFER |

REGISTER_INACTIVE | PENDING_ACTIVATION

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateArn": "string",
"certificateId": "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.

certificateArn (p. 525)

The certificate ARN.

Type: String
certificateId (p. 525)

The certificate identifier.

Type: String

Length Constraints: Fixed length of 64.

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

Errors
CertificateConflictException

Unable to verify the CA certificate used to sign the device certificate you are attempting to register.
This is happens when you have registered more than one CA certificate that has the same subject
field and public key.

HTTP Status Code: 409

CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

525
 AWS IoT API Reference
RegisterCertificate

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

526
 AWS IoT API Reference
RegisterCertificateWithoutCA

RegisterCertificateWithoutCA
Service: AWS IoT

Register a certificate that does not have a certificate authority (CA).

Request Syntax
POST /certificate/register-no-ca HTTP/1.1
Content-type: application/json

{
"certificatePem": "string",
"status": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

certificatePem (p. 527)

The certificate data, in PEM format.

Type: String

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

Required: Yes
status (p. 527)

The status of the register certificate request.

Type: String

Valid Values: ACTIVE | INACTIVE | REVOKED | PENDING_TRANSFER |

REGISTER_INACTIVE | PENDING_ACTIVATION

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificateArn": "string",
"certificateId": "string"
}

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

527
 AWS IoT API Reference
RegisterCertificateWithoutCA

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

certificateArn (p. 527)

The Amazon Resource Name (ARN) of the registered certificate.

Type: String
certificateId (p. 527)

The ID of the registered certificate. (The last part of the certificate ARN contains the certificate ID.

Type: String

Length Constraints: Fixed length of 64.

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

Errors
CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

528
 AWS IoT API Reference
RegisterCertificateWithoutCA

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

529
 AWS IoT API Reference
RegisterThing

RegisterThing
Service: AWS IoT

Provisions a thing in the device registry. RegisterThing calls other AWS IoT control plane APIs. These calls
might exceed your account level AWS IoT Throttling Limits and cause throttle errors. Please contact
AWS Customer Support to raise your throttling limits if necessary.

Requires permission to access the RegisterThing action.

Request Syntax
POST /things HTTP/1.1
Content-type: application/json

{
"parameters": {
"string" : "string"
},
"templateBody": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

parameters (p. 530)

The parameters for provisioning a thing. See Provisioning Templates for more information.

Type: String to string map

Required: No
templateBody (p. 530)

The provisioning template. See Provisioning Devices That Have Device Certificates for more
information.

Type: String

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"certificatePem": "string",
"resourceArns": {
"string" : "string"
}
}

530
 AWS IoT API Reference
RegisterThing

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.

certificatePem (p. 530)

The certificate data, in PEM format.

Type: String

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

resourceArns (p. 530)

ARNs for the generated resources.

Type: String to string map

Errors
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceRegistrationFailureException

The resource registration failed.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

531
 AWS IoT API Reference
RegisterThing

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

532
 AWS IoT API Reference
RejectCertificateTransfer

RejectCertificateTransfer
Service: AWS IoT

Rejects a pending certificate transfer. After AWS IoT rejects a certificate transfer, the certificate status
changes from PENDING_TRANSFER to INACTIVE.

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

This operation can only be called by the transfer destination. After it is called, the certificate will be
returned to the source's account in the INACTIVE state.

Requires permission to access the RejectCertificateTransfer action.

Request Syntax
PATCH /reject-certificate-transfer/certificateId HTTP/1.1
Content-type: application/json

{
"rejectReason": "string"
}

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 533)

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
The request accepts the following data in JSON format.

rejectReason (p. 533)

The reason the certificate transfer was rejected.

Type: String

Length Constraints: Maximum length of 128.

Required: No

Response Syntax
HTTP/1.1 200

533
 AWS IoT API Reference
RejectCertificateTransfer

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

TransferAlreadyCompletedException

You can't revert the certificate transfer because the transfer is already complete.

HTTP Status Code: 410

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

534
 AWS IoT API Reference
RejectCertificateTransfer

• AWS SDK for Ruby V3

535
 AWS IoT API Reference
RemoveThingFromBillingGroup

RemoveThingFromBillingGroup
Service: AWS IoT

Removes the given thing from the billing group.

Requires permission to access the RemoveThingFromBillingGroup action.

Request Syntax
PUT /billing-groups/removeThingFromBillingGroup 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. 536)

The ARN of the billing group.

Type: String

Required: No
billingGroupName (p. 536)

The name of the billing group.

Type: String

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

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

Required: No
thingArn (p. 536)

The ARN of the thing to be removed from the billing group.

Type: String

Required: No
thingName (p. 536)

The name of the thing to be removed from the billing group.

Type: String

536
 AWS IoT API Reference
RemoveThingFromBillingGroup

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

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

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

537
 AWS IoT API Reference
RemoveThingFromThingGroup

RemoveThingFromThingGroup
Service: AWS IoT

Remove the specified thing from the specified group.

You must specify either a thingGroupArn or a thingGroupName to identify the thing group and either
a thingArn or a thingName to identify the thing to remove from the thing group.

Requires permission to access the RemoveThingFromThingGroup action.

Request Syntax
PUT /thing-groups/removeThingFromThingGroup HTTP/1.1
Content-type: application/json

{
"thingArn": "string",
"thingGroupArn": "string",
"thingGroupName": "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.

thingArn (p. 538)

The ARN of the thing to remove from the group.

Type: String

Required: No
thingGroupArn (p. 538)

The group ARN.

Type: String

Required: No
thingGroupName (p. 538)

The group name.

Type: String

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

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

Required: No
thingName (p. 538)

The name of the thing to remove from the group.

538
 AWS IoT API Reference
RemoveThingFromThingGroup

Type: String

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

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

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

539
 AWS IoT API Reference
RemoveThingFromThingGroup

540
 AWS IoT API Reference
ReplaceTopicRule

ReplaceTopicRule
Service: AWS IoT

Replaces the rule. You must specify all parameters for the new rule. Creating rules is an administrator-
level action. Any user who has permission to create rules will be able to access data processed by the
rule.

Requires permission to access the ReplaceTopicRule action.

Request Syntax
PATCH /rules/ruleName HTTP/1.1
Content-type: application/json

{
"topicRulePayload": {
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",
"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {

541
 AWS IoT API Reference
ReplaceTopicRule

"batchMode": boolean,
"deliveryStreamName": "string",
"roleArn": "string",
"separator": "string"
},
"http": {
"auth": {
"sigv4": {
"roleArn": "string",
"serviceName": "string",
"signingRegion": "string"
}
},
"confirmationUrl": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"url": "string"
},
"iotAnalytics": {
"batchMode": boolean,
"channelArn": "string",
"channelName": "string",
"roleArn": "string"
},
"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",

542
 AWS IoT API Reference
ReplaceTopicRule

"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"republish": {
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",
"key": "string",
"roleArn": "string"
},
"salesforce": {
"token": "string",
"url": "string"
},
"sns": {
"messageFormat": "string",
"roleArn": "string",
"targetArn": "string"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},
"stepFunctions": {
"executionNamePrefix": "string",
"roleArn": "string",
"stateMachineName": "string"
},
"timestream": {
"databaseName": "string",
"dimensions": [
{
"name": "string",
"value": "string"
}
],
"roleArn": "string",
"tableName": "string",
"timestamp": {
"unit": "string",
"value": "string"
}
}
}
],
"awsIotSqlVersion": "string",
"description": "string",
"errorAction": {
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"

543
 AWS IoT API Reference
ReplaceTopicRule

},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",
"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {
"batchMode": boolean,
"deliveryStreamName": "string",
"roleArn": "string",
"separator": "string"
},
"http": {
"auth": {
"sigv4": {
"roleArn": "string",
"serviceName": "string",
"signingRegion": "string"
}
},
"confirmationUrl": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"url": "string"
},
"iotAnalytics": {
"batchMode": boolean,
"channelArn": "string",
"channelName": "string",
"roleArn": "string"

544
 AWS IoT API Reference
ReplaceTopicRule

},
"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"republish": {
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",
"key": "string",
"roleArn": "string"
},
"salesforce": {
"token": "string",
"url": "string"
},
"sns": {

545
 AWS IoT API Reference
ReplaceTopicRule

"messageFormat": "string",
"roleArn": "string",
"targetArn": "string"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},
"stepFunctions": {
"executionNamePrefix": "string",
"roleArn": "string",
"stateMachineName": "string"
},
"timestream": {
"databaseName": "string",
"dimensions": [
{
"name": "string",
"value": "string"
}
],
"roleArn": "string",
"tableName": "string",
"timestamp": {
"unit": "string",
"value": "string"
}
}
},
"ruleDisabled": boolean,
"sql": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 541)

The name of the rule.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

topicRulePayload (p. 541)

The rule payload.

Type: TopicRulePayload (p. 1013) object

Required: Yes

546
 AWS IoT API Reference
ReplaceTopicRule

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

SqlParseException

The Rule-SQL expression can't be parsed correctly.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

547
 AWS IoT API Reference
ReplaceTopicRule

• AWS SDK for Python

• AWS SDK for Ruby V3

548
 AWS IoT API Reference
SearchIndex

SearchIndex
Service: AWS IoT

The query search index.

Requires permission to access the SearchIndex action.

Request Syntax
POST /indices/search HTTP/1.1
Content-type: application/json

{
"indexName": "string",
"maxResults": number,
"nextToken": "string",
"queryString": "string",
"queryVersion": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

indexName (p. 549)

The search index name.

Type: String

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

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

Required: No
maxResults (p. 549)

The maximum number of results to return at one time.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 500.

Required: No
nextToken (p. 549)

The token used to get the next set of results, or null if there are no additional results.

Type: String

Required: No
queryString (p. 549)

The search query string.

549
 AWS IoT API Reference
SearchIndex

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 549)

The query version.

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"thingGroups": [
{
"attributes": {
"string" : "string"
},
"parentGroupNames": [ "string" ],
"thingGroupDescription": "string",
"thingGroupId": "string",
"thingGroupName": "string"
}
],
"things": [
{
"attributes": {
"string" : "string"
},
"connectivity": {
"connected": boolean,
"disconnectReason": "string",
"timestamp": number
},
"shadow": "string",
"thingGroupNames": [ "string" ],
"thingId": "string",
"thingName": "string",
"thingTypeName": "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.

nextToken (p. 550)

The token used to get the next set of results, or null if there are no additional results.

Type: String

550
 AWS IoT API Reference
SearchIndex

thingGroups (p. 550)

The thing groups that match the search query.

Type: Array of ThingGroupDocument (p. 989) objects

things (p. 550)

The things that match the search query.

Type: Array of ThingDocument (p. 987) objects

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

551
 AWS IoT API Reference
SearchIndex

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

552
 AWS IoT API Reference
SetDefaultAuthorizer

SetDefaultAuthorizer
Service: AWS IoT

Sets the default authorizer. This will be used if a websocket connection is made without specifying an
authorizer.

Requires permission to access the SetDefaultAuthorizer action.

Request Syntax
POST /default-authorizer HTTP/1.1
Content-type: application/json

{
"authorizerName": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

authorizerName (p. 553)

The authorizer name.

Type: String

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

Pattern: [\w=,@-]+

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizerArn": "string",
"authorizerName": "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.

authorizerArn (p. 553)

The authorizer ARN.

553
 AWS IoT API Reference
SetDefaultAuthorizer

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 553)

The authorizer name.

Type: String

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

Pattern: [\w=,@-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

554
 AWS IoT API Reference
SetDefaultAuthorizer

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

555
 AWS IoT API Reference
SetDefaultPolicyVersion

SetDefaultPolicyVersion
Service: AWS IoT

Sets the specified version of the specified policy as the policy's default (operative) version. This action
affects all certificates to which the policy is attached. To list the principals the policy is attached to, use
the ListPrincipalPolicies (p. 457) action.

Requires permission to access the SetDefaultPolicyVersion action.

Request Syntax
PATCH /policies/policyName/version/policyVersionId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 556)

The policy name.

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

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

Required: Yes
policyVersionId (p. 556)

The policy version ID.

Pattern: [0-9]+

Required: Yes

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

556
 AWS IoT API Reference
SetDefaultPolicyVersion

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

557
 AWS IoT API Reference
SetLoggingOptions

SetLoggingOptions
Service: AWS IoT

Sets the logging options.

NOTE: use of this command is not recommended. Use SetV2LoggingOptions instead.

Requires permission to access the SetLoggingOptions action.

Request Syntax
POST /loggingOptions HTTP/1.1
Content-type: application/json

{
"loggingOptionsPayload": {
"logLevel": "string",
"roleArn": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

loggingOptionsPayload (p. 558)

The logging options payload.

Type: LoggingOptionsPayload (p. 911) object

Required: Yes

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
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

558
 AWS IoT API Reference
SetLoggingOptions

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

559
 AWS IoT API Reference
SetV2LoggingLevel

SetV2LoggingLevel
Service: AWS IoT

Sets the logging level.

Requires permission to access the SetV2LoggingLevel action.

Request Syntax
POST /v2LoggingLevel HTTP/1.1
Content-type: application/json

{
"logLevel": "string",
"logTarget": {
"targetName": "string",
"targetType": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

logLevel (p. 560)

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: Yes
logTarget (p. 560)

The log target.

Type: LogTarget (p. 912) object

Required: Yes

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.

560
 AWS IoT API Reference
SetV2LoggingLevel

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

NotConfiguredException

The resource is not configured.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

561
 AWS IoT API Reference
SetV2LoggingOptions

SetV2LoggingOptions
Service: AWS IoT

Sets the logging options for the V2 logging service.

Requires permission to access the SetV2LoggingOptions action.

Request Syntax
POST /v2LoggingOptions HTTP/1.1
Content-type: application/json

{
"defaultLogLevel": "string",
"disableAllLogs": boolean,
"roleArn": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

defaultLogLevel (p. 562)

The default logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
disableAllLogs (p. 562)

If true all logs are disabled. The default is false.

Type: Boolean

Required: No
roleArn (p. 562)

The ARN of the role that allows IoT to write to Cloudwatch logs.

Type: String

Required: No

Response Syntax
HTTP/1.1 200

562
 AWS IoT API Reference
SetV2LoggingOptions

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

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

563
 AWS IoT API Reference
StartAuditMitigationActionsTask

StartAuditMitigationActionsTask
Service: AWS IoT

Starts a task that applies a set of mitigation actions to the specified target.

Requires permission to access the StartAuditMitigationActionsTask action.

Request Syntax
POST /audit/mitigationactions/tasks/taskId HTTP/1.1
Content-type: application/json

{
"auditCheckToActionsMapping": {
"string" : [ "string" ]
},
"clientRequestToken": "string",
"target": {
"auditCheckToReasonCodeFilter": {
"string" : [ "string" ]
},
"auditTaskId": "string",
"findingIds": [ "string" ]
}
}

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 564)

A unique identifier for the task. You can use this identifier to check the status of the task or to cancel
it.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

auditCheckToActionsMapping (p. 564)

For an audit check, specifies which mitigation actions to apply. Those actions must be defined in
your AWS accounts.

Type: String to array of strings map

Array Members: Minimum number of 1 item. Maximum number of 5 items.

Length Constraints: Maximum length of 128.

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

564
 AWS IoT API Reference
StartAuditMitigationActionsTask

Required: Yes
clientRequestToken (p. 564)

Each audit mitigation task must have a unique client request token. If you try to start a new task
with the same token as a task that already exists, an exception occurs. If you omit this value, a
unique client request token is generated automatically.

Type: String

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

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

Required: Yes
target (p. 564)

Specifies the audit findings to which the mitigation actions are applied. You can apply them to a
type of audit check, to all findings from an audit, or to a specific set of findings.

Type: AuditMitigationActionsTaskTarget (p. 806) object

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"taskId": "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.

taskId (p. 565)

The unique identifier for the audit mitigation task. This matches the taskId that you specified in
the request.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

565
 AWS IoT API Reference
StartAuditMitigationActionsTask

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

TaskAlreadyExistsException

This exception occurs if you attempt to start a task with the same task-id as an existing task but with
a different clientRequestToken.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

566
 AWS IoT API Reference
StartDetectMitigationActionsTask

StartDetectMitigationActionsTask
Service: AWS IoT

Starts a Device Defender ML Detect mitigation actions task.

Requires permission to access the StartDetectMitigationActionsTask action.

Request Syntax
PUT /detect/mitigationactions/tasks/taskId HTTP/1.1
Content-type: application/json

{
"actions": [ "string" ],
"clientRequestToken": "string",
"includeOnlyActiveViolations": boolean,
"includeSuppressedAlerts": boolean,
"target": {
"behaviorName": "string",
"securityProfileName": "string",
"violationIds": [ "string" ]
},
"violationEventOccurrenceRange": {
"endTime": number,
"startTime": number
}
}

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 567)

The unique identifier of the task.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

actions (p. 567)

The actions to be performed when a device has unexpected behavior.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

Length Constraints: Maximum length of 128.

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

Required: Yes

567
 AWS IoT API Reference
StartDetectMitigationActionsTask

clientRequestToken (p. 567)

Each mitigation action task must have a unique client request token. If you try to create a new task
with the same token as a task that already exists, an exception occurs. If you omit this value, AWS
SDKs will automatically generate a unique client request.

Type: String

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

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

Required: Yes
includeOnlyActiveViolations (p. 567)

Specifies to list only active violations.

Type: Boolean

Required: No
includeSuppressedAlerts (p. 567)

Specifies to include suppressed alerts.

Type: Boolean

Required: No
target (p. 567)

Specifies the ML Detect findings to which the mitigation actions are applied.

Type: DetectMitigationActionsTaskTarget (p. 860) object

Required: Yes
violationEventOccurrenceRange (p. 567)

Specifies the time period of which violation events occurred between.

Type: ViolationEventOccurrenceRange (p. 1022) object

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"taskId": "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.

568
 AWS IoT API Reference
StartDetectMitigationActionsTask

taskId (p. 568)

The unique identifier of the task.

Type: String

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

TaskAlreadyExistsException

This exception occurs if you attempt to start a task with the same task-id as an existing task but with
a different clientRequestToken.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

569
 AWS IoT API Reference
StartOnDemandAuditTask

StartOnDemandAuditTask
Service: AWS IoT

Starts an on-demand Device Defender audit.

Requires permission to access the StartOnDemandAuditTask action.

Request Syntax
POST /audit/tasks HTTP/1.1
Content-type: application/json

{
"targetCheckNames": [ "string" ]
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

targetCheckNames (p. 570)

Which checks are performed during the audit. The checks you specify must be enabled for your
account or an exception occurs. Use DescribeAccountAuditConfiguration to see the list of all
checks, including those that are enabled or UpdateAccountAuditConfiguration to select which
checks are enabled.

Type: Array of strings

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"taskId": "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.

taskId (p. 570)

The ID of the on-demand audit you started.

Type: String

570
 AWS IoT API Reference
StartOnDemandAuditTask

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

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

571
 AWS IoT API Reference
StartThingRegistrationTask

StartThingRegistrationTask
Service: AWS IoT

Creates a bulk thing provisioning task.

Requires permission to access the StartThingRegistrationTask action.

Request Syntax
POST /thing-registration-tasks HTTP/1.1
Content-type: application/json

{
"inputFileBucket": "string",
"inputFileKey": "string",
"roleArn": "string",
"templateBody": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

inputFileBucket (p. 572)

The S3 bucket that contains the input file.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 256.

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

Required: Yes
inputFileKey (p. 572)

The name of input file within the S3 bucket. This file contains a newline delimited JSON file. Each
line contains the parameter values to provision one device (thing).

Type: String

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

Pattern: [a-zA-Z0-9!_.*'()-\/]+

Required: Yes
roleArn (p. 572)

The IAM role ARN that grants permission the input file.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

572
 AWS IoT API Reference
StartThingRegistrationTask

templateBody (p. 572)

The provisioning template.

Type: String

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"taskId": "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.

taskId (p. 573)

The bulk thing provisioning task ID.

Type: String

Length Constraints: Maximum length of 40.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

573
 AWS IoT API Reference
StartThingRegistrationTask

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

574
 AWS IoT API Reference
StopThingRegistrationTask

StopThingRegistrationTask
Service: AWS IoT

Cancels a bulk thing provisioning task.

Requires permission to access the StopThingRegistrationTask action.

Request Syntax
PUT /thing-registration-tasks/taskId/cancel HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

taskId (p. 575)

The bulk thing provisioning task ID.

Length Constraints: Maximum length of 40.

Required: Yes

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

575
 AWS IoT API Reference
StopThingRegistrationTask

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

576
 AWS IoT API Reference
TagResource

TagResource
Service: AWS IoT

Adds to or modifies the tags of the given resource. Tags are metadata which can be used to manage a
resource.

Requires permission to access the TagResource action.

Request Syntax
POST /tags HTTP/1.1
Content-type: application/json

{
"resourceArn": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

resourceArn (p. 577)

The ARN of the resource.

Type: String

Required: Yes
tags (p. 577)

The new or modified tags for the resource.

Type: Array of Tag (p. 979) objects

Required: Yes

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.

577
 AWS IoT API Reference
TagResource

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

578
 AWS IoT API Reference
TestAuthorization

TestAuthorization
Service: AWS IoT

Tests if a specified principal is authorized to perform an AWS IoT action on a specified resource. Use this
to test and debug the authorization behavior of devices that connect to the AWS IoT device gateway.

Requires permission to access the TestAuthorization action.

Request Syntax
POST /test-authorization?clientId=clientId HTTP/1.1
Content-type: application/json

{
"authInfos": [
{
"actionType": "string",
"resources": [ "string" ]
}
],
"cognitoIdentityPoolId": "string",
"policyNamesToAdd": [ "string" ],
"policyNamesToSkip": [ "string" ],
"principal": "string"
}

URI Request Parameters

The request uses the following URI parameters.

clientId (p. 579)

The MQTT client ID.

Request Body
The request accepts the following data in JSON format.

authInfos (p. 579)

A list of authorization info objects. Simulating authorization will create a response for each
authInfo object in the list.

Type: Array of AuthInfo (p. 811) objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: Yes
cognitoIdentityPoolId (p. 579)

The Cognito identity pool ID.

Type: String

Required: No
policyNamesToAdd (p. 579)

When testing custom authorization, the policies specified here are treated as if they are attached to
the principal being authorized.

579
 AWS IoT API Reference
TestAuthorization

Type: Array of strings

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

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

Required: No
policyNamesToSkip (p. 579)

When testing custom authorization, the policies specified here are treated as if they are not attached
to the principal being authorized.

Type: Array of strings

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

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

Required: No
principal (p. 579)

The principal. Valid principals are CertificateArn (arn:aws:iot:region:accountId:cert/certificateId),

thingGroupArn (arn:aws:iot:region:accountId:thinggroup/groupName) and CognitoId (region:id).

Type: String

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authResults": [
{
"allowed": {
"policies": [
{
"policyArn": "string",
"policyName": "string"
}
]
},
"authDecision": "string",
"authInfo": {
"actionType": "string",
"resources": [ "string" ]
},
"denied": {
"explicitDeny": {
"policies": [
{
"policyArn": "string",
"policyName": "string"
}
]
},
"implicitDeny": {
"policies": [
{

580
 AWS IoT API Reference
TestAuthorization

"policyArn": "string",
"policyName": "string"
}
]
}
},
"missingContextValues": [ "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.

authResults (p. 580)

The authentication results.

Type: Array of AuthResult (p. 816) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

581
 AWS IoT API Reference
TestAuthorization

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

582
 AWS IoT API Reference
TestInvokeAuthorizer

TestInvokeAuthorizer
Service: AWS IoT

Tests a custom authorization behavior by invoking a specified custom authorizer. Use this to test and
debug the custom authorization behavior of devices that connect to the AWS IoT device gateway.

Requires permission to access the TestInvokeAuthorizer action.

Request Syntax
POST /authorizer/authorizerName/test HTTP/1.1
Content-type: application/json

{
"httpContext": {
"headers": {
"string" : "string"
},
"queryString": "string"
},
"mqttContext": {
"clientId": "string",
"password": blob,
"username": "string"
},
"tlsContext": {
"serverName": "string"
},
"token": "string",
"tokenSignature": "string"
}

URI Request Parameters

The request uses the following URI parameters.

authorizerName (p. 583)

The custom authorizer name.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

httpContext (p. 583)

Specifies a test HTTP authorization request.

Type: HttpContext (p. 880) object

Required: No

583
 AWS IoT API Reference
TestInvokeAuthorizer

mqttContext (p. 583)

Specifies a test MQTT authorization request.

Type: MqttContext (p. 923) object

Required: No
tlsContext (p. 583)

Specifies a test TLS authorization request.

Type: TlsContext (p. 1004) object

Required: No
token (p. 583)

The token returned by your custom authentication service.

Type: String

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

Required: No
tokenSignature (p. 583)

The signature made with the token and your custom authentication service's private key. This value
must be Base-64-encoded.

Type: String

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

Pattern: [A-Za-z0-9+/]+={0,2}

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"disconnectAfterInSeconds": number,
"isAuthenticated": boolean,
"policyDocuments": [ "string" ],
"principalId": "string",
"refreshAfterInSeconds": number
}

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.

disconnectAfterInSeconds (p. 584)

The number of seconds after which the connection is terminated.

584
 AWS IoT API Reference
TestInvokeAuthorizer

Type: Integer
isAuthenticated (p. 584)

True if the token is authenticated, otherwise false.

Type: Boolean
policyDocuments (p. 584)

IAM policy documents.

Type: Array of strings

principalId (p. 584)

The principal ID.

Type: String

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

Pattern: [a-zA-Z0-9]+
refreshAfterInSeconds (p. 584)

The number of seconds after which the temporary credentials are refreshed.

Type: Integer

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

InvalidResponseException

The response is invalid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

585
 AWS IoT API Reference
TestInvokeAuthorizer

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

586
 AWS IoT API Reference
TransferCertificate

TransferCertificate
Service: AWS IoT

Transfers the specified certificate to the specified AWS account.

Requires permission to access the TransferCertificate action.

You can cancel the transfer until it is acknowledged by the recipient.

No notification is sent to the transfer destination's account. It is up to the caller to notify the transfer
target.

The certificate being transferred must not be in the ACTIVE state. You can use the UpdateCertificate
(p. 607) action to deactivate it.

The certificate must not have any policies attached to it. You can use the DetachPolicy (p. 317) action to
detach them.

Request Syntax
PATCH /transfer-certificate/certificateId?targetAwsAccount=targetAwsAccount HTTP/1.1
Content-type: application/json

{
"transferMessage": "string"
}

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 587)

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
targetAwsAccount (p. 587)

The AWS account.

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

transferMessage (p. 587)

The transfer message.

587
 AWS IoT API Reference
TransferCertificate

Type: String

Length Constraints: Maximum length of 128.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"transferredCertificateArn": "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.

transferredCertificateArn (p. 588)

The ARN of the certificate.

Type: String

Errors
CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

588
 AWS IoT API Reference
TransferCertificate

HTTP Status Code: 400

TransferConflictException

You can't transfer the certificate because authorization policies are still attached.

HTTP Status Code: 409

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

589
 AWS IoT API Reference
UntagResource

UntagResource
Service: AWS IoT

Removes the given tags (metadata) from the resource.

Requires permission to access the UntagResource action.

Request Syntax
POST /untag HTTP/1.1
Content-type: application/json

{
"resourceArn": "string",
"tagKeys": [ "string" ]
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

resourceArn (p. 590)

The ARN of the resource.

Type: String

Required: Yes
tagKeys (p. 590)

A list of the keys of the tags to be removed from the resource.

Type: Array of strings

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

Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: Yes

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.

590
 AWS IoT API Reference
UntagResource

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

591
 AWS IoT API Reference
UpdateAccountAuditConfiguration

UpdateAccountAuditConfiguration
Service: AWS IoT

Configures or reconfigures the Device Defender audit settings for this account. Settings include how
audit notifications are sent and which audit checks are enabled or disabled.

Requires permission to access the UpdateAccountAuditConfiguration action.

Request Syntax
PATCH /audit/configuration HTTP/1.1
Content-type: application/json

{
"auditCheckConfigurations": {
"string" : {
"enabled": boolean
}
},
"auditNotificationTargetConfigurations": {
"string" : {
"enabled": boolean,
"roleArn": "string",
"targetArn": "string"
}
},
"roleArn": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

auditCheckConfigurations (p. 592)

Specifies which audit checks are enabled and disabled for this account. Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
currently enabled.

Some data collection might start immediately when certain checks are enabled. When a check is
disabled, any data collected so far in relation to the check is deleted.

You cannot disable a check if it's used by any scheduled audit. You must first delete the check from
the scheduled audit or delete the scheduled audit itself.

On the first call to UpdateAccountAuditConfiguration, this parameter is required and must

specify at least one enabled check.

Type: String to AuditCheckConfiguration (p. 798) object map

Required: No
auditNotificationTargetConfigurations (p. 592)

Information about the targets to which audit notifications are sent.

592
 AWS IoT API Reference
UpdateAccountAuditConfiguration

Type: String to AuditNotificationTarget (p. 807) object map

Valid Keys: SNS

Required: No
roleArn (p. 592)

The Amazon Resource Name (ARN) of the role that grants permission to AWS IoT to access
information about your devices, policies, certificates, and other items as required when performing
an audit.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

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

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

593
 AWS IoT API Reference
UpdateAccountAuditConfiguration

• AWS SDK for Python

• AWS SDK for Ruby V3

594
 AWS IoT API Reference
UpdateAuditSuppression

UpdateAuditSuppression
Service: AWS IoT

Updates a Device Defender audit suppression.

Request Syntax
PATCH /audit/suppressions/update HTTP/1.1
Content-type: application/json

{
"checkName": "string",
"description": "string",
"expirationDate": number,
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"suppressIndefinitely": boolean
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

checkName (p. 595)

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: Yes
description (p. 595)

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No

595
 AWS IoT API Reference
UpdateAuditSuppression

expirationDate (p. 595)

The expiration date (epoch timestamp in seconds) that you want the suppression to adhere to.

Type: Timestamp

Required: No
resourceIdentifier (p. 595)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: Yes
suppressIndefinitely (p. 595)

Indicates whether a suppression should exist indefinitely or not.

Type: Boolean

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

596
 AWS IoT API Reference
UpdateAuditSuppression

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

597
 AWS IoT API Reference
UpdateAuthorizer

UpdateAuthorizer
Service: AWS IoT

Updates an authorizer.

Requires permission to access the UpdateAuthorizer action.

Request Syntax
PUT /authorizer/authorizerName HTTP/1.1
Content-type: application/json

{
"authorizerFunctionArn": "string",
"status": "string",
"tokenKeyName": "string",
"tokenSigningPublicKeys": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

authorizerName (p. 598)

The authorizer name.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

authorizerFunctionArn (p. 598)

The ARN of the authorizer's Lambda function.

Type: String

Length Constraints: Maximum length of 2048.

Required: No
status (p. 598)

The status of the update authorizer request.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No

598
 AWS IoT API Reference
UpdateAuthorizer

tokenKeyName (p. 598)

The key used to extract the token from the HTTP headers.

Type: String

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

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

Required: No
tokenSigningPublicKeys (p. 598)

The public keys used to verify the token signature.

Type: String to string map

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

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

Value Length Constraints: Maximum length of 5120.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"authorizerArn": "string",
"authorizerName": "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.

authorizerArn (p. 599)

The authorizer ARN.

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 599)

The authorizer name.

Type: String

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

Pattern: [\w=,@-]+

599
 AWS IoT API Reference
UpdateAuthorizer

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

600
 AWS IoT API Reference
UpdateBillingGroup

UpdateBillingGroup
Service: AWS IoT

Updates information about the billing group.

Requires permission to access the UpdateBillingGroup action.

Request Syntax
PATCH /billing-groups/billingGroupName HTTP/1.1
Content-type: application/json

{
"billingGroupProperties": {
"billingGroupDescription": "string"
},
"expectedVersion": number
}

URI Request Parameters

The request uses the following URI parameters.

billingGroupName (p. 601)

The name of the billing group.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

billingGroupProperties (p. 601)

The properties of the billing group.

Type: BillingGroupProperties (p. 832) object

Required: Yes
expectedVersion (p. 601)

The expected version of the billing group. If the version of the billing group does not match the
expected version specified in the request, the UpdateBillingGroup request is rejected with a
VersionConflictException.

Type: Long

Required: No

Response Syntax
HTTP/1.1 200

601
 AWS IoT API Reference
UpdateBillingGroup

Content-type: application/json

{
"version": number
}

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.

version (p. 601)

The latest version of the billing group.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go

602
 AWS IoT API Reference
UpdateBillingGroup

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

603
 AWS IoT API Reference
UpdateCACertificate

UpdateCACertificate
Service: AWS IoT

Updates a registered CA certificate.

Requires permission to access the UpdateCACertificate action.

Request Syntax
PUT /cacertificate/caCertificateId?
newAutoRegistrationStatus=newAutoRegistrationStatus&newStatus=newStatus HTTP/1.1
Content-type: application/json

{
"registrationConfig": {
"roleArn": "string",
"templateBody": "string"
},
"removeAutoRegistration": boolean
}

URI Request Parameters

The request uses the following URI parameters.

caCertificateId (p. 604)

The CA certificate identifier.

Length Constraints: Fixed length of 64.

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

Required: Yes
newAutoRegistrationStatus (p. 604)

The new value for the auto registration status. Valid values are: "ENABLE" or "DISABLE".

Valid Values: ENABLE | DISABLE

newStatus (p. 604)

The updated status of the CA certificate.

Note: The status value REGISTER_INACTIVE is deprecated and should not be used.

Valid Values: ACTIVE | INACTIVE

Request Body
The request accepts the following data in JSON format.

registrationConfig (p. 604)

Information about the registration configuration.

Type: RegistrationConfig (p. 947) object

Required: No

604
 AWS IoT API Reference
UpdateCACertificate

removeAutoRegistration (p. 604)

If true, removes auto registration.

Type: Boolean

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

605
 AWS IoT API Reference
UpdateCACertificate

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

606
 AWS IoT API Reference
UpdateCertificate

UpdateCertificate
Service: AWS IoT

Updates the status of the specified certificate. This operation is idempotent.

Requires permission to access the UpdateCertificate action.

Certificates must be in the ACTIVE state to authenticate devices that use a certificate to connect to AWS
IoT.

Within a few minutes of updating a certificate from the ACTIVE state to any other state, AWS IoT
disconnects all devices that used that certificate to connect. Devices cannot use a certificate that is not in
the ACTIVE state to reconnect.

Request Syntax
PUT /certificates/certificateId?newStatus=newStatus HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 607)

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
newStatus (p. 607)

The new status.

Note: Setting the status to PENDING_TRANSFER or PENDING_ACTIVATION will result in an exception

being thrown. PENDING_TRANSFER and PENDING_ACTIVATION are statuses used internally by AWS
IoT. They are not intended for developer use.

Note: The status value REGISTER_INACTIVE is deprecated and should not be used.

Valid Values: ACTIVE | INACTIVE | REVOKED | PENDING_TRANSFER |

REGISTER_INACTIVE | PENDING_ACTIVATION

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

607
 AWS IoT API Reference
UpdateCertificate

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

Errors
CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

608
 AWS IoT API Reference
UpdateCertificate

• AWS SDK for Ruby V3

609
 AWS IoT API Reference
UpdateCustomMetric

UpdateCustomMetric
Service: AWS IoT

Updates a Device Defender detect custom metric.

Requires permission to access the UpdateCustomMetric action.

Request Syntax
PATCH /custom-metric/metricName HTTP/1.1
Content-type: application/json

{
"displayName": "string"
}

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 610)

The name of the custom metric. Cannot be updated.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

displayName (p. 610)

Field represents a friendly name in the console for the custom metric, it doesn't have to be unique.
Don't use this name as the metric identifier in the device metric report. Can be updated.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Graph}\x20]*

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"creationDate": number,
"displayName": "string",
"lastModifiedDate": number,

610
 AWS IoT API Reference
UpdateCustomMetric

"metricArn": "string",
"metricName": "string",
"metricType": "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.

creationDate (p. 610)

The creation date of the custom metric in milliseconds since epoch.

Type: Timestamp
displayName (p. 610)

A friendly name in the console for the custom metric

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Graph}\x20]*
lastModifiedDate (p. 610)

The time the custom metric was last modified in milliseconds since epoch.

Type: Timestamp
metricArn (p. 610)

The Amazon Resource Number (ARN) of the custom metric.

Type: String
metricName (p. 610)

The name of the custom metric.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
metricType (p. 610)

The type of the custom metric. Types include string-list, ip-address-list, number-list,
and number.

Type: String

Valid Values: string-list | ip-address-list | number-list | number

Errors
InternalFailureException

An unexpected error has occurred.

611
 AWS IoT API Reference
UpdateCustomMetric

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

612
 AWS IoT API Reference
UpdateDimension

UpdateDimension
Service: AWS IoT

Updates the definition for a dimension. You cannot change the type of a dimension after it is created
(you can delete it and recreate it).

Requires permission to access the UpdateDimension action.

Request Syntax
PATCH /dimensions/name HTTP/1.1
Content-type: application/json

{
"stringValues": [ "string" ]
}

URI Request Parameters

The request uses the following URI parameters.

name (p. 613)

A unique identifier for the dimension. Choose something that describes the type and value to make
it easy to remember what it does.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

stringValues (p. 613)

Specifies the value or list of values for the dimension. For TOPIC_FILTER dimensions, this is a
pattern used to match the MQTT topic (for example, "admin/#").

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

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

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"arn": "string",
"creationDate": number,

613
 AWS IoT API Reference
UpdateDimension

"lastModifiedDate": number,
"name": "string",
"stringValues": [ "string" ],
"type": "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.

arn (p. 613)

The Amazon Resource Name (ARN)of the created dimension.

Type: String
creationDate (p. 613)

The date and time, in milliseconds since epoch, when the dimension was initially created.

Type: Timestamp
lastModifiedDate (p. 613)

The date and time, in milliseconds since epoch, when the dimension was most recently updated.

Type: Timestamp
name (p. 613)

A unique identifier for the dimension.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
stringValues (p. 613)

The value or list of values used to scope the dimension. For example, for topic filters, this is the
pattern used to match the MQTT topic name.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

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

type (p. 613)

The type of the dimension.

Type: String

Valid Values: TOPIC_FILTER

Errors
InternalFailureException

An unexpected error has occurred.

614
 AWS IoT API Reference
UpdateDimension

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

615
 AWS IoT API Reference
UpdateDomainConfiguration

UpdateDomainConfiguration
Service: AWS IoT

Updates values stored in the domain configuration. Domain configurations for default endpoints can't be
updated.

Requires permission to access the UpdateDomainConfiguration action.

Request Syntax
PUT /domainConfigurations/domainConfigurationName HTTP/1.1
Content-type: application/json

{
"authorizerConfig": {
"allowAuthorizerOverride": boolean,
"defaultAuthorizerName": "string"
},
"domainConfigurationStatus": "string",
"removeAuthorizerConfig": boolean
}

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 616)

The name of the domain configuration to be updated.

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

Pattern: [\w.:-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

authorizerConfig (p. 616)

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 812) object

Required: No
domainConfigurationStatus (p. 616)

The status to which the domain configuration should be updated.

Type: String

Valid Values: ENABLED | DISABLED

Required: No

616
 AWS IoT API Reference
UpdateDomainConfiguration

removeAuthorizerConfig (p. 616)

Removes the authorization configuration from a domain.

Type: Boolean

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"domainConfigurationArn": "string",
"domainConfigurationName": "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.

domainConfigurationArn (p. 617)

The ARN of the domain configuration that was updated.

Type: String
domainConfigurationName (p. 617)

The name of the domain configuration that was updated.

Type: String

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

Pattern: [\w.:-]+

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

617
 AWS IoT API Reference
UpdateDomainConfiguration

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

618
 AWS IoT API Reference
UpdateDynamicThingGroup

UpdateDynamicThingGroup
Service: AWS IoT

Updates a dynamic thing group.

Requires permission to access the UpdateDynamicThingGroup action.

Request Syntax
PATCH /dynamic-thing-groups/thingGroupName HTTP/1.1
Content-type: application/json

{
"expectedVersion": number,
"indexName": "string",
"queryString": "string",
"queryVersion": "string",
"thingGroupProperties": {
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean
},
"thingGroupDescription": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

thingGroupName (p. 619)

The name of the dynamic thing group to update.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

expectedVersion (p. 619)

The expected version of the dynamic thing group to update.

Type: Long

Required: No
indexName (p. 619)

The dynamic thing group index to update.

619
 AWS IoT API Reference
UpdateDynamicThingGroup

Note
Currently one index is supported: AWS_Things.

Type: String

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

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

Required: No
queryString (p. 619)

The dynamic thing group search query string to update.

Type: String

Length Constraints: Minimum length of 1.

Required: No
queryVersion (p. 619)

The dynamic thing group query version to update.

Note
Currently one query version is supported: "2017-09-30". If not specified, the query version
defaults to this value.

Type: String

Required: No
thingGroupProperties (p. 619)

The dynamic thing group properties to update.

Type: ThingGroupProperties (p. 993) object

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"version": number
}

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.

version (p. 620)

The dynamic thing group version.

Type: Long

620
 AWS IoT API Reference
UpdateDynamicThingGroup

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

621
 AWS IoT API Reference
UpdateEventConfigurations

UpdateEventConfigurations
Service: AWS IoT

Updates the event configurations.

Requires permission to access the UpdateEventConfigurations action.

Request Syntax
PATCH /event-configurations HTTP/1.1
Content-type: application/json

{
"eventConfigurations": {
"string" : {
"Enabled": boolean
}
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

eventConfigurations (p. 622)

The new event configuration values.

Type: String to Configuration (p. 851) object map

Valid Keys: THING | THING_GROUP | THING_TYPE | THING_GROUP_MEMBERSHIP |

THING_GROUP_HIERARCHY | THING_TYPE_ASSOCIATION | JOB | JOB_EXECUTION |
POLICY | CERTIFICATE | CA_CERTIFICATE

Required: No

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

622
 AWS IoT API Reference
UpdateEventConfigurations

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

623
 AWS IoT API Reference
UpdateFleetMetric

UpdateFleetMetric
Service: AWS IoT

Updates the data for a fleet metric.

Requires permission to access the UpdateFleetMetric action.

Request Syntax
PATCH /fleet-metric/metricName HTTP/1.1
Content-type: application/json

{
"aggregationField": "string",
"aggregationType": {
"name": "string",
"values": [ "string" ]
},
"description": "string",
"expectedVersion": number,
"indexName": "string",
"period": number,
"queryString": "string",
"queryVersion": "string",
"unit": "string"
}

URI Request Parameters

The request uses the following URI parameters.

metricName (p. 624)

The name of the fleet metric to update.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

aggregationField (p. 624)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
aggregationType (p. 624)

The type of the aggregation query.

Type: AggregationType (p. 791) object

624
 AWS IoT API Reference
UpdateFleetMetric

Required: No
description (p. 624)

The description of the fleet metric.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [\p{Graph}\x20]*

Required: No
expectedVersion (p. 624)

The expected version of the fleet metric record in the registry.

Type: Long

Required: No
indexName (p. 624)

The name of the index to search.

Type: String

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

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

Required: Yes
period (p. 624)

The time in seconds between fleet metric emissions. Range [60(1 min), 86400(1 day)] and must be
multiple of 60.

Type: Integer

Valid Range: Minimum value of 60. Maximum value of 86400.

Required: No
queryString (p. 624)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: No
queryVersion (p. 624)

The version of the query.

Type: String

Required: No
unit (p. 624)

Used to support unit transformation such as milliseconds to seconds. The unit must be supported by
CW metric.

625
 AWS IoT API Reference
UpdateFleetMetric

Type: String

Valid Values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes |

Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits
| Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/
Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second
| Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None

Required: No

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
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

626
 AWS IoT API Reference
UpdateFleetMetric

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

627
 AWS IoT API Reference
UpdateIndexingConfiguration

UpdateIndexingConfiguration
Service: AWS IoT

Updates the search configuration.

Requires permission to access the UpdateIndexingConfiguration action.

Request Syntax
POST /indexing/config HTTP/1.1
Content-type: application/json

{
"thingGroupIndexingConfiguration": {
"customFields": [
{
"name": "string",
"type": "string"
}
],
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"thingGroupIndexingMode": "string"
},
"thingIndexingConfiguration": {
"customFields": [
{
"name": "string",
"type": "string"
}
],
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"thingConnectivityIndexingMode": "string",
"thingIndexingMode": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

thingGroupIndexingConfiguration (p. 628)

Thing group indexing configuration.

Type: ThingGroupIndexingConfiguration (p. 991) object

Required: No

628
 AWS IoT API Reference
UpdateIndexingConfiguration

thingIndexingConfiguration (p. 628)

Thing indexing configuration.

Type: ThingIndexingConfiguration (p. 994) object

Required: No

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

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

629
 AWS IoT API Reference
UpdateIndexingConfiguration

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

630
 AWS IoT API Reference
UpdateJob

UpdateJob
Service: AWS IoT

Updates supported fields of the specified job.

Requires permission to access the UpdateJob action.

Request Syntax
PATCH /jobs/jobId?namespaceId=namespaceId HTTP/1.1
Content-type: application/json

{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"description": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 631)

The ID of the job to be updated.

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

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

Required: Yes
namespaceId (p. 631)

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

631
 AWS IoT API Reference
UpdateJob

When you specify a value for this parameter, AWS IoT Core sends jobs notifications 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.

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

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

Request Body
The request accepts the following data in JSON format.

abortConfig (p. 631)

Allows you to create criteria to abort a job.

Type: AbortConfig (p. 782) object

Required: No
description (p. 631)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
jobExecutionsRolloutConfig (p. 631)

Allows you to create a staged rollout of the job.

Type: JobExecutionsRolloutConfig (p. 895) object

Required: No
presignedUrlConfig (p. 631)

Configuration information for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 937) object

Required: No
timeoutConfig (p. 631)

Specifies the amount of time each device has to finish its execution of the job. The timer is started
when the job execution status is set to IN_PROGRESS. If the job execution status is not set to
another terminal state before the time expires, it will be automatically set to TIMED_OUT.

Type: TimeoutConfig (p. 999) object

Required: No

632
 AWS IoT API Reference
UpdateJob

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
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

633
 AWS IoT API Reference
UpdateMitigationAction

UpdateMitigationAction
Service: AWS IoT

Updates the definition for the specified mitigation action.

Requires permission to access the UpdateMitigationAction action.

Request Syntax
PATCH /mitigationactions/actions/actionName HTTP/1.1
Content-type: application/json

{
"actionParams": {
"addThingsToThingGroupParams": {
"overrideDynamicGroups": boolean,
"thingGroupNames": [ "string" ]
},
"enableIoTLoggingParams": {
"logLevel": "string",
"roleArnForLogging": "string"
},
"publishFindingToSnsParams": {
"topicArn": "string"
},
"replaceDefaultPolicyVersionParams": {
"templateName": "string"
},
"updateCACertificateParams": {
"action": "string"
},
"updateDeviceCertificateParams": {
"action": "string"
}
},
"roleArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

actionName (p. 634)

The friendly name for the mitigation action. You cannot change the name by using
UpdateMitigationAction. Instead, you must delete and recreate the mitigation action with the
new name.

Length Constraints: Maximum length of 128.

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

634
 AWS IoT API Reference
UpdateMitigationAction

actionParams (p. 634)

Defines the type of action and the parameters for that action.

Type: MitigationActionParams (p. 921) object

Required: No
roleArn (p. 634)

The ARN of the IAM role that is used to apply the mitigation action.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"actionArn": "string",
"actionId": "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.

actionArn (p. 635)

The ARN for the new mitigation action.

Type: String
actionId (p. 635)

A unique identifier for the mitigation action.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

635
 AWS IoT API Reference
UpdateMitigationAction

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

636
 AWS IoT API Reference
UpdateProvisioningTemplate

UpdateProvisioningTemplate
Service: AWS IoT

Updates a fleet provisioning template.

Requires permission to access the UpdateProvisioningTemplate action.

Request Syntax
PATCH /provisioning-templates/templateName HTTP/1.1
Content-type: application/json

{
"defaultVersionId": number,
"description": "string",
"enabled": boolean,
"preProvisioningHook": {
"payloadVersion": "string",
"targetArn": "string"
},
"provisioningRoleArn": "string",
"removePreProvisioningHook": boolean
}

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 637)

The name of the fleet provisioning template.

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

Pattern: ^[0-9A-Za-z_-]+$

Required: Yes

Request Body
The request accepts the following data in JSON format.

defaultVersionId (p. 637)

The ID of the default provisioning template version.

Type: Integer

Required: No
description (p. 637)

The description of the fleet provisioning template.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: [^\p{C}]*

637
 AWS IoT API Reference
UpdateProvisioningTemplate

Required: No
enabled (p. 637)

True to enable the fleet provisioning template, otherwise false.

Type: Boolean

Required: No
preProvisioningHook (p. 637)

Updates the pre-provisioning hook template.

Type: ProvisioningHook (p. 938) object

Required: No
provisioningRoleArn (p. 637)

The ARN of the role associated with the provisioning template. This IoT role grants permission to
provision a device.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
removePreProvisioningHook (p. 637)

Removes pre-provisioning hook template.

Type: Boolean

Required: No

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

638
 AWS IoT API Reference
UpdateProvisioningTemplate

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

639
 AWS IoT API Reference
UpdateRoleAlias

UpdateRoleAlias
Service: AWS IoT

Updates a role alias.

Requires permission to access the UpdateRoleAlias action.

Request Syntax
PUT /role-aliases/roleAlias HTTP/1.1
Content-type: application/json

{
"credentialDurationSeconds": number,
"roleArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

roleAlias (p. 640)

The role alias to update.

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

Pattern: [\w=,@-]+

Required: Yes

Request Body
The request accepts the following data in JSON format.

credentialDurationSeconds (p. 640)

The number of seconds the credential will be valid.

Type: Integer

Valid Range: Minimum value of 900. Maximum value of 43200.

Required: No
roleArn (p. 640)

The role ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

Response Syntax
HTTP/1.1 200

640
 AWS IoT API Reference
UpdateRoleAlias

Content-type: application/json

{
"roleAlias": "string",
"roleAliasArn": "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.

roleAlias (p. 640)

The role alias.

Type: String

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

Pattern: [\w=,@-]+
roleAliasArn (p. 640)

The role alias ARN.

Type: String

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

641
 AWS IoT API Reference
UpdateRoleAlias

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

642
 AWS IoT API Reference
UpdateScheduledAudit

UpdateScheduledAudit
Service: AWS IoT

Updates a scheduled audit, including which checks are performed and how often the audit takes place.

Requires permission to access the UpdateScheduledAudit action.

Request Syntax
PATCH /audit/scheduledaudits/scheduledAuditName HTTP/1.1
Content-type: application/json

{
"dayOfMonth": "string",
"dayOfWeek": "string",
"frequency": "string",
"targetCheckNames": [ "string" ]
}

URI Request Parameters

The request uses the following URI parameters.

scheduledAuditName (p. 643)

The name of the scheduled audit. (Max. 128 chars)

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

dayOfMonth (p. 643)

The day of the month on which the scheduled audit takes place. This can be 1 through 31 or LAST.
This field is required if the frequency parameter is set to MONTHLY. If days 29-31 are specified, and
the month does not have that many days, the audit takes place on the "LAST" day of the month.

Type: String

Pattern: ^([1-9]|[12][0-9]|3[01])$|^LAST$

Required: No
dayOfWeek (p. 643)

The day of the week on which the scheduled audit takes place. This can be one of SUN, MON, TUE,
WED, THU, FRI, or SAT. This field is required if the "frequency" parameter is set to WEEKLY or
BIWEEKLY.

Type: String

Valid Values: SUN | MON | TUE | WED | THU | FRI | SAT

643
 AWS IoT API Reference
UpdateScheduledAudit

Required: No
frequency (p. 643)

How often the scheduled audit takes place, either DAILY, WEEKLY, BIWEEKLY, or MONTHLY. The start
time of each audit is determined by the system.

Type: String

Valid Values: DAILY | WEEKLY | BIWEEKLY | MONTHLY

Required: No
targetCheckNames (p. 643)

Which checks are performed during the scheduled audit. Checks must be enabled for your account.
(Use DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: Array of strings

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"scheduledAuditArn": "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.

scheduledAuditArn (p. 644)

The ARN of the scheduled audit.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

644
 AWS IoT API Reference
UpdateScheduledAudit

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

645
 AWS IoT API Reference
UpdateSecurityProfile

UpdateSecurityProfile
Service: AWS IoT

Updates a Device Defender security profile.

Requires permission to access the UpdateSecurityProfile action.

Request Syntax
PATCH /security-profiles/securityProfileName?expectedVersion=expectedVersion HTTP/1.1
Content-type: application/json

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"deleteAdditionalMetricsToRetain": boolean,
"deleteAlertTargets": boolean,
"deleteBehaviors": boolean,

646
 AWS IoT API Reference
UpdateSecurityProfile

"securityProfileDescription": "string"
}

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 646)

The expected version of the security profile. A new version is generated whenever the
security profile is updated. If you specify a value that is different from the actual version, a
VersionConflictException is thrown.
securityProfileName (p. 646)

The name of the security profile you want to update.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

additionalMetricsToRetain (p. 646)

This parameter has been deprecated.

Please use UpdateSecurityProfile:additionalMetricsToRetainV2 (p. 647) instead.

A list of metrics whose data is retained (stored). By default, data is retained for any metric used
in the profile's behaviors, but it is also retained for any metric specified here. Can be used with
custom metrics; cannot be used with dimensions.

Type: Array of strings

Required: No
additionalMetricsToRetainV2 (p. 646)

A list of metrics whose data is retained (stored). By default, data is retained for any metric used in
the profile's behaviors, but it is also retained for any metric specified here. Can be used with custom
metrics; cannot be used with dimensions.

Type: Array of MetricToRetain (p. 916) objects

Required: No
alertTargets (p. 646)

Where the alerts are sent. (Alerts are always sent to the console.)

Type: String to AlertTarget (p. 792) object map

Valid Keys: SNS

Required: No

647
 AWS IoT API Reference
UpdateSecurityProfile

behaviors (p. 646)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 825) objects

Array Members: Maximum number of 100 items.

Required: No
deleteAdditionalMetricsToRetain (p. 646)

If true, delete all additionalMetricsToRetain defined for this security profile. If any
additionalMetricsToRetain are defined in the current invocation, an exception occurs.

Type: Boolean

Required: No
deleteAlertTargets (p. 646)

If true, delete all alertTargets defined for this security profile. If any alertTargets are defined
in the current invocation, an exception occurs.

Type: Boolean

Required: No
deleteBehaviors (p. 646)

If true, delete all behaviors defined for this security profile. If any behaviors are defined in the
current invocation, an exception occurs.

Type: Boolean

Required: No
securityProfileDescription (p. 646)

A description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"

648
 AWS IoT API Reference
UpdateSecurityProfile

}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"creationDate": number,
"lastModifiedDate": number,
"securityProfileArn": "string",
"securityProfileDescription": "string",
"securityProfileName": "string",
"version": number
}

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.

additionalMetricsToRetain (p. 648)

This parameter has been deprecated.

Please use UpdateSecurityProfile:additionalMetricsToRetainV2 (p. 650) instead.

A list of metrics whose data is retained (stored). By default, data is retained for any metric used in
the security profile's behaviors, but it is also retained for any metric specified here.

Type: Array of strings

649
 AWS IoT API Reference
UpdateSecurityProfile

additionalMetricsToRetainV2 (p. 648)

A list of metrics whose data is retained (stored). By default, data is retained for any metric used in
the profile's behaviors, but it is also retained for any metric specified here. Can be used with custom
metrics; cannot be used with dimensions.

Type: Array of MetricToRetain (p. 916) objects

alertTargets (p. 648)

Where the alerts are sent. (Alerts are always sent to the console.)

Type: String to AlertTarget (p. 792) object map

Valid Keys: SNS

behaviors (p. 648)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 825) objects

Array Members: Maximum number of 100 items.

creationDate (p. 648)

The time the security profile was created.

Type: Timestamp
lastModifiedDate (p. 648)

The time the security profile was last modified.

Type: Timestamp
securityProfileArn (p. 648)

The ARN of the security profile that was updated.

Type: String
securityProfileDescription (p. 648)

The description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*
securityProfileName (p. 648)

The name of the security profile that was updated.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
version (p. 648)

The updated version of the security profile.

Type: Long

650
 AWS IoT API Reference
UpdateSecurityProfile

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

651
 AWS IoT API Reference
UpdateStream

UpdateStream
Service: AWS IoT

Updates an existing stream. The stream version will be incremented by one.

Requires permission to access the UpdateStream action.

Request Syntax
PUT /streams/streamId HTTP/1.1
Content-type: application/json

{
"description": "string",
"files": [
{
"fileId": number,
"s3Location": {
"bucket": "string",
"key": "string",
"version": "string"
}
}
],
"roleArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

streamId (p. 652)

The stream ID.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

description (p. 652)

The description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 652)

The files associated with the stream.

652
 AWS IoT API Reference
UpdateStream

Type: Array of StreamFile (p. 975) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: No
roleArn (p. 652)

An IAM role that allows the IoT service principal assumes to access your S3 files.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"description": "string",
"streamArn": "string",
"streamId": "string",
"streamVersion": number
}

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. 653)

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
streamArn (p. 653)

The stream ARN.

Type: String
streamId (p. 653)

The stream ID.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
streamVersion (p. 653)

The stream version.

653
 AWS IoT API Reference
UpdateStream

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 65535.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

654
 AWS IoT API Reference
UpdateThing

UpdateThing
Service: AWS IoT

Updates the data for a thing.

Requires permission to access the UpdateThing action.

Request Syntax
PATCH /things/thingName HTTP/1.1
Content-type: application/json

{
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean
},
"expectedVersion": number,
"removeThingType": boolean,
"thingTypeName": "string"
}

URI Request Parameters

The request uses the following URI parameters.

thingName (p. 655)

The name of the thing to update.

You can't change a thing's name. To change a thing's name, you must create a new thing, give it the
new name, and then delete the old thing.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

attributePayload (p. 655)

A list of thing attributes, a JSON string containing name-value pairs. For example:

{\"attributes\":{\"name1\":\"value2\"}}

This data is used to add new attributes or update existing attributes.

Type: AttributePayload (p. 797) object

Required: No

655
 AWS IoT API Reference
UpdateThing

expectedVersion (p. 655)

The expected version of the thing record in the registry. If the version of the record in the registry
does not match the expected version specified in the request, the UpdateThing request is rejected
with a VersionConflictException.

Type: Long

Required: No
removeThingType (p. 655)

Remove a thing type association. If true, the association is removed.

Type: Boolean

Required: No
thingTypeName (p. 655)

The name of the thing type.

Type: String

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

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

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

656
 AWS IoT API Reference
UpdateThing

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

657
 AWS IoT API Reference
UpdateThingGroup

UpdateThingGroup
Service: AWS IoT

Update a thing group.

Requires permission to access the UpdateThingGroup action.

Request Syntax
PATCH /thing-groups/thingGroupName HTTP/1.1
Content-type: application/json

{
"expectedVersion": number,
"thingGroupProperties": {
"attributePayload": {
"attributes": {
"string" : "string"
},
"merge": boolean
},
"thingGroupDescription": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

thingGroupName (p. 658)

The thing group to update.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

expectedVersion (p. 658)

The expected version of the thing group. If this does not match the version of the thing group being
updated, the update will fail.

Type: Long

Required: No
thingGroupProperties (p. 658)

The thing group properties.

Type: ThingGroupProperties (p. 993) object

Required: Yes

658
 AWS IoT API Reference
UpdateThingGroup

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"version": number
}

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.

version (p. 659)

The version of the updated thing group.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

659
 AWS IoT API Reference
UpdateThingGroup

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

660
 AWS IoT API Reference
UpdateThingGroupsForThing

UpdateThingGroupsForThing
Service: AWS IoT

Updates the groups to which the thing belongs.

Requires permission to access the UpdateThingGroupsForThing action.

Request Syntax
PUT /thing-groups/updateThingGroupsForThing HTTP/1.1
Content-type: application/json

{
"overrideDynamicGroups": boolean,
"thingGroupsToAdd": [ "string" ],
"thingGroupsToRemove": [ "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.

overrideDynamicGroups (p. 661)

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
thingGroupsToAdd (p. 661)

The groups to which the thing will be added.

Type: Array of strings

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

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

Required: No
thingGroupsToRemove (p. 661)

The groups from which the thing will be removed.

Type: Array of strings

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

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

Required: No

661
 AWS IoT API Reference
UpdateThingGroupsForThing

thingName (p. 661)

The thing whose group memberships will be updated.

Type: String

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

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

Required: No

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

662
 AWS IoT API Reference
UpdateThingGroupsForThing

• AWS SDK for Python

• AWS SDK for Ruby V3

663
 AWS IoT API Reference
UpdateTopicRuleDestination

UpdateTopicRuleDestination
Service: AWS IoT

Updates a topic rule destination. You use this to change the status, endpoint URL, or confirmation URL of
the destination.

Requires permission to access the UpdateTopicRuleDestination action.

Request Syntax
PATCH /destinations HTTP/1.1
Content-type: application/json

{
"arn": "string",
"status": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

arn (p. 664)

The ARN of the topic rule destination.

Type: String

Required: Yes
status (p. 664)

The status of the topic rule destination. Valid values are:

IN_PROGRESS

A topic rule destination was created but has not been confirmed. You can set
status to IN_PROGRESS by calling UpdateTopicRuleDestination. Calling
UpdateTopicRuleDestination causes a new confirmation challenge to be sent to your
confirmation endpoint.
ENABLED

Confirmation was completed, and traffic to this destination is allowed. You can set status to
DISABLED by calling UpdateTopicRuleDestination.
DISABLED

Confirmation was completed, and traffic to this destination is not allowed. You can set status
to ENABLED by calling UpdateTopicRuleDestination.
ERROR

Confirmation could not be completed, for example if the confirmation timed out. You can call
GetTopicRuleDestination for details about the error. You can set status to IN_PROGRESS
by calling UpdateTopicRuleDestination. Calling UpdateTopicRuleDestination causes a
new confirmation challenge to be sent to your confirmation endpoint.

664
 AWS IoT API Reference
UpdateTopicRuleDestination

Type: String

Valid Values: ENABLED | IN_PROGRESS | DISABLED | ERROR | DELETING

Required: Yes

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
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript

665
 AWS IoT API Reference
UpdateTopicRuleDestination

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

666
 AWS IoT API Reference
ValidateSecurityProfileBehaviors

ValidateSecurityProfileBehaviors
Service: AWS IoT

Validates a Device Defender security profile behaviors specification.

Requires permission to access the ValidateSecurityProfileBehaviors action.

Request Syntax
POST /security-profile-behaviors/validate HTTP/1.1
Content-type: application/json

{
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
]
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

behaviors (p. 667)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 825) objects

Array Members: Maximum number of 100 items.

667
 AWS IoT API Reference
ValidateSecurityProfileBehaviors

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"valid": boolean,
"validationErrors": [
{
"errorMessage": "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.

valid (p. 668)

True if the behaviors were valid.

Type: Boolean
validationErrors (p. 668)

The list of any errors found in the behaviors.

Type: Array of ValidationError (p. 1018) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

668
 AWS IoT API Reference
AWS IoT data

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT data

The following actions are supported by AWS IoT data:

• DeleteThingShadow (p. 670)

• GetRetainedMessage (p. 673)
• GetThingShadow (p. 676)
• ListNamedShadowsForThing (p. 679)
• ListRetainedMessages (p. 682)
• Publish (p. 685)
• UpdateThingShadow (p. 687)

669
 AWS IoT API Reference
DeleteThingShadow

DeleteThingShadow
Service: AWS IoT data

Deletes the shadow for the specified thing.

Requires permission to access the DeleteThingShadow action.

For more information, see DeleteThingShadow in the AWS IoT Developer Guide.

Request Syntax
DELETE /things/thingName/shadow?name=shadowName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

shadowName (p. 670)

The name of the shadow.

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

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 670)

The name of the thing.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

payload

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

The response returns the following as the HTTP body.

payload (p. 670)

The state information, in JSON format.

670
 AWS IoT API Reference
DeleteThingShadow

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

UnsupportedDocumentEncodingException

The document encoding is not supported.

HTTP Status Code: 415

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

671
 AWS IoT API Reference
DeleteThingShadow

• AWS SDK for Ruby V3

672
 AWS IoT API Reference
GetRetainedMessage

GetRetainedMessage
Service: AWS IoT data

Gets the details of a single retained message for the specified topic.

This action returns the message payload of the retained message, which can incur messaging costs. To
list only the topic names of the retained messages, call ListRetainedMessages.

Requires permission to access the GetRetainedMessage action.

For more information about messaging costs, see AWS IoT Core pricing - Messaging.

Request Syntax
GET /retainedMessage/topic HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

topic (p. 673)

The topic name of the retained message to retrieve.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"lastModifiedTime": number,
"payload": blob,
"qos": number,
"topic": "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.

lastModifiedTime (p. 673)

The Epoch date and time, in milliseconds, when the retained message was stored by AWS IoT.

Type: Long
payload (p. 673)

The Base64-encoded message payload of the retained message body.

673
 AWS IoT API Reference
GetRetainedMessage

Type: Base64-encoded binary data object

qos (p. 673)

The quality of service (QoS) level used to publish the retained message.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 1.

topic (p. 673)

The topic name to which the retained message was published.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

674
 AWS IoT API Reference
GetRetainedMessage

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

675
 AWS IoT API Reference
GetThingShadow

GetThingShadow
Service: AWS IoT data

Gets the shadow for the specified thing.

Requires permission to access the GetThingShadow action.

For more information, see GetThingShadow in the AWS IoT Developer Guide.

Request Syntax
GET /things/thingName/shadow?name=shadowName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

shadowName (p. 676)

The name of the shadow.

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

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 676)

The name of the thing.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

payload

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

The response returns the following as the HTTP body.

payload (p. 676)

The state information, in JSON format.

676
 AWS IoT API Reference
GetThingShadow

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

UnsupportedDocumentEncodingException

The document encoding is not supported.

HTTP Status Code: 415

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

677
 AWS IoT API Reference
GetThingShadow

• AWS SDK for Ruby V3

678
 AWS IoT API Reference
ListNamedShadowsForThing

ListNamedShadowsForThing
Service: AWS IoT data

Lists the shadows for the specified thing.

Requires permission to access the ListNamedShadowsForThing action.

Request Syntax
GET /api/things/shadow/ListNamedShadowsForThing/thingName?
nextToken=nextToken&pageSize=pageSize HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

nextToken (p. 679)

The token to retrieve the next set of results.

pageSize (p. 679)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 100.

thingName (p. 679)

The name of the thing.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"results": [ "string" ],
"timestamp": number
}

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.

679
 AWS IoT API Reference
ListNamedShadowsForThing

nextToken (p. 679)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
results (p. 679)

The list of shadows for the specified thing.

Type: Array of strings

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

Pattern: [a-zA-Z0-9:_-]+
timestamp (p. 679)

The Epoch date and time the response was generated by AWS IoT.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

680
 AWS IoT API Reference
ListNamedShadowsForThing

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

681
 AWS IoT API Reference
ListRetainedMessages

ListRetainedMessages
Service: AWS IoT data

Lists summary information about the retained messages stored for the account.

This action returns only the topic names of the retained messages. It doesn't return any message
payloads. Although this action doesn't return a message payload, it can still incur messaging costs.

To get the message payload of a retained message, call GetRetainedMessage with the topic name of the
retained message.

Requires permission to access the ListRetainedMessages action.

For more information about messaging costs, see AWS IoT Core pricing - Messaging.

Request Syntax
GET /retainedMessage?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 682)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 200.

nextToken (p. 682)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"retainedTopics": [
{
"lastModifiedTime": number,
"payloadSize": number,
"qos": number,
"topic": "string"
}
]
}

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

682
 AWS IoT API Reference
ListRetainedMessages

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

nextToken (p. 682)

The token for the next set of results, or null if there are no additional results.

Type: String
retainedTopics (p. 682)

A summary list the account's retained messages. The information returned doesn't include the
message payloads of the retained messages.

Type: Array of RetainedMessageSummary (p. 1026) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2

683
 AWS IoT API Reference
ListRetainedMessages

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

684
 AWS IoT API Reference
Publish

Publish
Service: AWS IoT data

Publishes an MQTT message.

Requires permission to access the Publish action.

For more information about MQTT messages, see MQTT Protocol in the AWS IoT Developer Guide.

For more information about messaging costs, see AWS IoT Core pricing - Messaging.

Request Syntax
POST /topics/topic?qos=qos&retain=retain HTTP/1.1

payload

URI Request Parameters

The request uses the following URI parameters.

qos (p. 685)

The Quality of Service (QoS) level.

Valid Range: Minimum value of 0. Maximum value of 1.

retain (p. 685)

A Boolean value that determines whether to set the RETAIN flag when the message is published.

Setting the RETAIN flag causes the message to be retained and sent to new subscribers to the topic.

Valid values: true | false

Default value: false

topic (p. 685)

The name of the MQTT topic.

Required: Yes

Request Body
The request accepts the following binary data.

payload (p. 685)

The message body. MQTT accepts text, binary, and empty (null) message payloads.

Publishing an empty (null) payload with retain = true deletes the retained message identified by
topic from AWS IoT Core.

Response Syntax
HTTP/1.1 200

685
 AWS IoT API Reference
Publish

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

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

686
 AWS IoT API Reference
UpdateThingShadow

UpdateThingShadow
Service: AWS IoT data

Updates the shadow for the specified thing.

Requires permission to access the UpdateThingShadow action.

For more information, see UpdateThingShadow in the AWS IoT Developer Guide.

Request Syntax
POST /things/thingName/shadow?name=shadowName HTTP/1.1

payload

URI Request Parameters

The request uses the following URI parameters.

shadowName (p. 687)

The name of the shadow.

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

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 687)

The name of the thing.

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

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

Required: Yes

Request Body
The request accepts the following binary data.

payload (p. 687)

The state information, in JSON format.

Required: Yes

Response Syntax
HTTP/1.1 200

payload

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

687
 AWS IoT API Reference
UpdateThingShadow

The response returns the following as the HTTP body.

payload (p. 687)

The state information, in JSON format.

Errors
ConflictException

The specified version does not match the version of the document.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

RequestEntityTooLargeException

The payload exceeds the maximum size allowed.

HTTP Status Code: 413

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

UnsupportedDocumentEncodingException

The document encoding is not supported.

HTTP Status Code: 415

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

688
 AWS IoT API Reference
AWS IoT jobs data

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT jobs data

The following actions are supported by AWS IoT jobs data:

• DescribeJobExecution (p. 690)

• GetPendingJobExecutions (p. 693)
• StartNextPendingJobExecution (p. 696)
• UpdateJobExecution (p. 699)

689
 AWS IoT API Reference
DescribeJobExecution

DescribeJobExecution
Service: AWS IoT jobs data

Gets details of a job execution.

Requires permission to access the DescribeJobExecution action.

Request Syntax
GET /things/thingName/jobs/jobId?
executionNumber=executionNumber&includeJobDocument=includeJobDocument&namespaceId=namespaceId
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

executionNumber (p. 690)

Optional. A number that identifies a particular job execution on a particular device. If not specified,
the latest job execution is returned.
includeJobDocument (p. 690)

Optional. Unless set to false, the response contains the job document. The default is true.
jobId (p. 690)

The unique identifier assigned to this job when it was created.

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

Pattern: [a-zA-Z0-9_-]+|^\$next

Required: Yes
namespaceId (p. 690)

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 notifications 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.

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

Pattern: [a-zA-Z0-9_-]+
thingName (p. 690)

The thing name associated with the device the job execution is running on.

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

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

Required: Yes

690
 AWS IoT API Reference
DescribeJobExecution

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"execution": {
"approximateSecondsBeforeTimedOut": number,
"executionNumber": number,
"jobDocument": "string",
"jobId": "string",
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,
"status": "string",
"statusDetails": {
"string" : "string"
},
"thingName": "string",
"versionNumber": number
}
}

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.

execution (p. 691)

Contains data about a job execution.

Type: JobExecution (p. 1028) object

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InvalidRequestException

The contents of the request were invalid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

691
 AWS IoT API Reference
DescribeJobExecution

HTTP Status Code: 503

TerminalStateException

The job is in a terminal state.

HTTP Status Code: 410

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

692
 AWS IoT API Reference
GetPendingJobExecutions

GetPendingJobExecutions
Service: AWS IoT jobs data

Gets the list of all jobs for a thing that are not in a terminal status.

Requires permission to access the GetPendingJobExecutions action.

Request Syntax
GET /things/thingName/jobs?namespaceId=namespaceId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

namespaceId (p. 693)

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 notifications 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.

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

Pattern: [a-zA-Z0-9_-]+
thingName (p. 693)

The name of the thing that is executing the job.

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

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

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"inProgressJobs": [
{
"executionNumber": number,
"jobId": "string",
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,

693
 AWS IoT API Reference
GetPendingJobExecutions

"versionNumber": number
}
],
"queuedJobs": [
{
"executionNumber": number,
"jobId": "string",
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,
"versionNumber": number
}
]
}

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.

inProgressJobs (p. 693)

A list of JobExecutionSummary objects with status IN_PROGRESS.

Type: Array of JobExecutionSummary (p. 1032) objects

queuedJobs (p. 693)

A list of JobExecutionSummary objects with status QUEUED.

Type: Array of JobExecutionSummary (p. 1032) objects

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InvalidRequestException

The contents of the request were invalid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

694
 AWS IoT API Reference
GetPendingJobExecutions

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

695
 AWS IoT API Reference
StartNextPendingJobExecution

StartNextPendingJobExecution
Service: AWS IoT jobs data

Gets and starts the next pending (status IN_PROGRESS or QUEUED) job execution for a thing.

Requires permission to access the StartNextPendingJobExecution action.

Request Syntax
PUT /things/thingName/jobs/$next?namespaceId=namespaceId HTTP/1.1
Content-type: application/json

{
"statusDetails": {
"string" : "string"
},
"stepTimeoutInMinutes": number
}

URI Request Parameters

The request uses the following URI parameters.

namespaceId (p. 696)

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 notifications 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.

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

Pattern: [a-zA-Z0-9_-]+
thingName (p. 696)

The name of the thing associated with the device.

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

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

Required: Yes

Request Body
The request accepts the following data in JSON format.

statusDetails (p. 696)

A collection of name/value pairs that describe the status of the job execution. If not specified, the
statusDetails are unchanged.

The maximum length of the value in the name/value pair is 1,024 characters.

696
 AWS IoT API Reference
StartNextPendingJobExecution

Type: String to string map

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

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

Value Length Constraints: Minimum length of 1.

Value Pattern: [^\p{C}]+

Required: No
stepTimeoutInMinutes (p. 696)

Specifies the amount of time this device has to finish execution of this job. If the job execution
status is not set to a terminal state before this timer expires, or before the timer is reset (by calling
UpdateJobExecution, setting the status to IN_PROGRESS, and specifying a new timeout value in
field stepTimeoutInMinutes) the job execution status will be automatically set to TIMED_OUT.
Note that setting the step timeout has no effect on the in progress timeout that may have been
specified when the job was created (CreateJob using field timeoutConfig).

Valid values for this parameter range from 1 to 10080 (1 minute to 7 days).

Type: Long

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"execution": {
"approximateSecondsBeforeTimedOut": number,
"executionNumber": number,
"jobDocument": "string",
"jobId": "string",
"lastUpdatedAt": number,
"queuedAt": number,
"startedAt": number,
"status": "string",
"statusDetails": {
"string" : "string"
},
"thingName": "string",
"versionNumber": number
}
}

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.

execution (p. 697)

A JobExecution object.

Type: JobExecution (p. 1028) object

697
 AWS IoT API Reference
StartNextPendingJobExecution

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InvalidRequestException

The contents of the request were invalid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

698
 AWS IoT API Reference
UpdateJobExecution

UpdateJobExecution
Service: AWS IoT jobs data

Updates the status of a job execution.

Requires permission to access the UpdateJobExecution action.

Request Syntax
POST /things/thingName/jobs/jobId?namespaceId=namespaceId HTTP/1.1
Content-type: application/json

{
"executionNumber": number,
"expectedVersion": number,
"includeJobDocument": boolean,
"includeJobExecutionState": boolean,
"status": "string",
"statusDetails": {
"string" : "string"
},
"stepTimeoutInMinutes": number
}

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 699)

The unique identifier assigned to this job when it was created.

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

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

Required: Yes
namespaceId (p. 699)

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 notifications 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.

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

Pattern: [a-zA-Z0-9_-]+
thingName (p. 699)

The name of the thing associated with the device.

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

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

699
 AWS IoT API Reference
UpdateJobExecution

Required: Yes

Request Body
The request accepts the following data in JSON format.

executionNumber (p. 699)

Optional. A number that identifies a particular job execution on a particular device.

Type: Long

Required: No
expectedVersion (p. 699)

Optional. The expected current version of the job execution. Each time you update the job execution,
its version is incremented. If the version of the job execution stored in Jobs does not match,
the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the
current job execution status data is returned. (This makes it unnecessary to perform a separate
DescribeJobExecution request in order to obtain the job execution status data.)

Type: Long

Required: No
includeJobDocument (p. 699)

Optional. When set to true, the response contains the job document. The default is false.

Type: Boolean

Required: No
includeJobExecutionState (p. 699)

Optional. When included and set to true, the response contains the JobExecutionState data. The
default is false.

Type: Boolean

Required: No
status (p. 699)

The new status for the job execution (IN_PROGRESS, FAILED, SUCCESS, or REJECTED). This must be
specified on every update.

Type: String

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED

Required: Yes
statusDetails (p. 699)

Optional. A collection of name/value pairs that describe the status of the job execution. If not
specified, the statusDetails are unchanged.

The maximum length of the value in the name/value pair is 1,024 characters.

Type: String to string map

700
 AWS IoT API Reference
UpdateJobExecution

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

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

Value Length Constraints: Minimum length of 1.

Value Pattern: [^\p{C}]+

Required: No
stepTimeoutInMinutes (p. 699)

Specifies the amount of time this device has to finish execution of this job. If the job execution status
is not set to a terminal state before this timer expires, or before the timer is reset (by again calling
UpdateJobExecution, setting the status to IN_PROGRESS, and specifying a new timeout value
in this field) the job execution status will be automatically set to TIMED_OUT. Note that setting or
resetting the step timeout has no effect on the in progress timeout that may have been specified
when the job was created (CreateJob using field timeoutConfig).

Valid values for this parameter range from 1 to 10080 (1 minute to 7 days). A value of -1 is also valid
and will cancel the current step timer (created by an earlier use of UpdateJobExecutionRequest).

Type: Long

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"executionState": {
"status": "string",
"statusDetails": {
"string" : "string"
},
"versionNumber": number
},
"jobDocument": "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.

executionState (p. 701)

A JobExecutionState object.

Type: JobExecutionState (p. 1031) object

jobDocument (p. 701)

The contents of the Job Documents.

Type: String

Length Constraints: Maximum length of 32768.

701
 AWS IoT API Reference
AWS IoT Core Device Advisor

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InvalidRequestException

The contents of the request were invalid.

HTTP Status Code: 400

InvalidStateTransitionException

An update attempted to change the job execution to a state that is invalid because of the job
execution's current state (for example, an attempt to change a request in state SUCCESS to state
IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT Core Device Advisor

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

702
 AWS IoT API Reference
AWS IoT Core Device Advisor

• CreateSuiteDefinition (p. 704)

• DeleteSuiteDefinition (p. 707)
• GetSuiteDefinition (p. 709)
• GetSuiteRun (p. 712)
• GetSuiteRunReport (p. 716)
• ListSuiteDefinitions (p. 718)
• ListSuiteRuns (p. 720)
• ListTagsForResource (p. 723)
• StartSuiteRun (p. 725)
• StopSuiteRun (p. 728)
• TagResource (p. 730)
• UntagResource (p. 732)
• UpdateSuiteDefinition (p. 734)

703
 AWS IoT API Reference
CreateSuiteDefinition

CreateSuiteDefinition
Service: AWS IoT Core Device Advisor

Creates a Device Advisor test suite.

Requires permission to access the CreateSuiteDefinition action.

Request Syntax
POST /suiteDefinitions HTTP/1.1
Content-type: application/json

{
"suiteDefinitionConfiguration": {
"devicePermissionRoleArn": "string",
"devices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"rootGroup": "string",
"suiteDefinitionName": "string"
},
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

suiteDefinitionConfiguration (p. 704)

Creates a Device Advisor test suite with suite definition configuration.

Type: SuiteDefinitionConfiguration (p. 1036) object

Required: Yes
tags (p. 704)

The tags to be attached to the suite definition.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

704
 AWS IoT API Reference
CreateSuiteDefinition

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"createdAt": number,
"suiteDefinitionArn": "string",
"suiteDefinitionId": "string",
"suiteDefinitionName": "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.

createdAt (p. 705)

Creates a Device Advisor test suite with TimeStamp of when it was created.

Type: Timestamp
suiteDefinitionArn (p. 705)

Creates a Device Advisor test suite with Amazon Resource Name (ARN).

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteDefinitionId (p. 705)

Creates a Device Advisor test suite with suite UUID.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionName (p. 705)

Creates a Device Advisor test suite with suite definition name.

Type: String

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

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

705
 AWS IoT API Reference
CreateSuiteDefinition

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

706
 AWS IoT API Reference
DeleteSuiteDefinition

DeleteSuiteDefinition
Service: AWS IoT Core Device Advisor

Deletes a Device Advisor test suite.

Requires permission to access the DeleteSuiteDefinition action.

Request Syntax
DELETE /suiteDefinitions/suiteDefinitionId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 707)

Suite definition ID of the test suite to be deleted.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes

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
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

707
 AWS IoT API Reference
DeleteSuiteDefinition

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

708
 AWS IoT API Reference
GetSuiteDefinition

GetSuiteDefinition
Service: AWS IoT Core Device Advisor

Gets information about a Device Advisor test suite.

Requires permission to access the GetSuiteDefinition action.

Request Syntax
GET /suiteDefinitions/suiteDefinitionId?suiteDefinitionVersion=suiteDefinitionVersion
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 709)

Suite definition ID of the test suite to get.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteDefinitionVersion (p. 709)

Suite definition version of the test suite to get.

Length Constraints: Minimum length of 2. Maximum length of 255.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"createdAt": number,
"lastModifiedAt": number,
"latestVersion": "string",
"suiteDefinitionArn": "string",
"suiteDefinitionConfiguration": {
"devicePermissionRoleArn": "string",
"devices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"rootGroup": "string",
"suiteDefinitionName": "string"
},
"suiteDefinitionId": "string",
"suiteDefinitionVersion": "string",

709
 AWS IoT API Reference
GetSuiteDefinition

"tags": {
"string" : "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.

createdAt (p. 709)

Date (in Unix epoch time) when the suite definition was created.

Type: Timestamp
lastModifiedAt (p. 709)

Date (in Unix epoch time) when the suite definition was last modified.

Type: Timestamp
latestVersion (p. 709)

Latest suite definition version of the suite definition.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

suiteDefinitionArn (p. 709)

The ARN of the suite definition.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteDefinitionConfiguration (p. 709)

Suite configuration of the suite definition.

Type: SuiteDefinitionConfiguration (p. 1036) object

suiteDefinitionId (p. 709)

Suite definition ID of the suite definition.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionVersion (p. 709)

Suite definition version of the suite definition.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

tags (p. 709)

Tags attached to the suite definition.

Type: String to string map

710
 AWS IoT API Reference
GetSuiteDefinition

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

HTTP Status Code: 404

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

711
 AWS IoT API Reference
GetSuiteRun

GetSuiteRun
Service: AWS IoT Core Device Advisor

Gets information about a Device Advisor test suite run.

Requires permission to access the GetSuiteRun action.

Request Syntax
GET /suiteDefinitions/suiteDefinitionId/suiteRuns/suiteRunId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 712)

Suite definition ID for the test suite run.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteRunId (p. 712)

Suite run ID for the test suite run.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"endTime": number,
"errorReason": "string",
"startTime": number,
"status": "string",
"suiteDefinitionId": "string",
"suiteDefinitionVersion": "string",
"suiteRunArn": "string",
"suiteRunConfiguration": {
"primaryDevice": {
"certificateArn": "string",
"thingArn": "string"
},
"selectedTestList": [ "string" ]
},
"suiteRunId": "string",
"tags": {
"string" : "string"

712
 AWS IoT API Reference
GetSuiteRun

},
"testResult": {
"groups": [
{
"groupId": "string",
"groupName": "string",
"tests": [
{
"endTime": number,
"failure": "string",
"logUrl": "string",
"startTime": number,
"status": "string",
"testCaseDefinitionId": "string",
"testCaseDefinitionName": "string",
"testCaseRunId": "string",
"warnings": "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.

endTime (p. 712)

Date (in Unix epoch time) when the test suite run ended.

Type: Timestamp
errorReason (p. 712)

Error reason for any test suite run failure.

Type: String
startTime (p. 712)

Date (in Unix epoch time) when the test suite run was started.

Type: Timestamp
status (p. 712)

Status for the test suite run.

Type: String

Valid Values: PASS | FAIL | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR
suiteDefinitionId (p. 712)

Suite definition ID for the test suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

713
 AWS IoT API Reference
GetSuiteRun

suiteDefinitionVersion (p. 712)

Suite definition version for the test suite run.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

suiteRunArn (p. 712)

The ARN of the suite run.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteRunConfiguration (p. 712)

Suite run configuration for the test suite run.

Type: SuiteRunConfiguration (p. 1040) object

suiteRunId (p. 712)

Suite run ID for the test suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

tags (p. 712)

The tags attached to the suite run.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 1. Maximum length of 256.

testResult (p. 712)

Test results for the test suite run.

Type: TestResult (p. 1045) object

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

HTTP Status Code: 404

ValidationException

Sends invalid request exception.

714
 AWS IoT API Reference
GetSuiteRun

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

715
 AWS IoT API Reference
GetSuiteRunReport

GetSuiteRunReport
Service: AWS IoT Core Device Advisor

Gets a report download link for a successful Device Advisor qualifying test suite run.

Requires permission to access the GetSuiteRunReport action.

Request Syntax
GET /suiteDefinitions/suiteDefinitionId/suiteRuns/suiteRunId/report HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 716)

Suite definition ID of the test suite.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteRunId (p. 716)

Suite run ID of the test suite run.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"qualificationReportDownloadUrl": "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.

qualificationReportDownloadUrl (p. 716)

Download URL of the qualification report.

Type: String

716
 AWS IoT API Reference
GetSuiteRunReport

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

HTTP Status Code: 404

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

717
 AWS IoT API Reference
ListSuiteDefinitions

ListSuiteDefinitions
Service: AWS IoT Core Device Advisor

Lists the Device Advisor test suites you have created.

Requires permission to access the ListSuiteDefinitions action.

Request Syntax
GET /suiteDefinitions?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 718)

The maximum number of results to return at once.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken (p. 718)

A token used to get the next set of results.

Length Constraints: Maximum length of 2000.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"suiteDefinitionInformationList": [
{
"createdAt": number,
"defaultDevices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"suiteDefinitionId": "string",
"suiteDefinitionName": "string"
}
]
}

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

718
 AWS IoT API Reference
ListSuiteDefinitions

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

nextToken (p. 718)

A token used to get the next set of results.

Type: String

Length Constraints: Maximum length of 2000.

suiteDefinitionInformationList (p. 718)

An array of objects that provide summaries of information about the suite definitions in the list.

Type: Array of SuiteDefinitionInformation (p. 1038) objects

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

719
 AWS IoT API Reference
ListSuiteRuns

ListSuiteRuns
Service: AWS IoT Core Device Advisor

Lists the runs of the specified Device Advisor test suite. You can list all runs of the test suite, or the runs
of a specific version of the test suite.

Requires permission to access the ListSuiteRuns action.

Request Syntax
GET /suiteRuns?
maxResults=maxResults&nextToken=nextToken&suiteDefinitionId=suiteDefinitionId&suiteDefinitionVersion=su
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 720)

The maximum number of results to return at once.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken (p. 720)

A token to retrieve the next set of results.

Length Constraints: Maximum length of 2000.

suiteDefinitionId (p. 720)

Lists the test suite runs of the specified test suite based on suite definition ID.

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionVersion (p. 720)

Must be passed along with suiteDefinitionId. Lists the test suite runs of the specified test suite based
on suite definition version.

Length Constraints: Minimum length of 2. Maximum length of 255.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"suiteRunsList": [
{
"createdAt": number,
"endAt": number,
"failed": number,

720
 AWS IoT API Reference
ListSuiteRuns

"passed": number,
"startedAt": number,
"status": "string",
"suiteDefinitionId": "string",
"suiteDefinitionName": "string",
"suiteDefinitionVersion": "string",
"suiteRunId": "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.

nextToken (p. 720)

A token to retrieve the next set of results.

Type: String

Length Constraints: Maximum length of 2000.

suiteRunsList (p. 720)

An array of objects that provide summaries of information about the suite runs in the list.

Type: Array of SuiteRunInformation (p. 1041) objects

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

721
 AWS IoT API Reference
ListSuiteRuns

• AWS SDK for Ruby V3

722
 AWS IoT API Reference
ListTagsForResource

ListTagsForResource
Service: AWS IoT Core Device Advisor

Lists the tags attached to an IoT Device Advisor resource.

Requires permission to access the ListTagsForResource action.

Request Syntax
GET /tags/resourceArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceArn (p. 723)

The ARN of the IoT Device Advisor resource.

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"tags": {
"string" : "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.

tags (p. 723)

The tags attached to the IoT Device Advisor resource.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 1. Maximum length of 256.

723
 AWS IoT API Reference
ListTagsForResource

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

HTTP Status Code: 404

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

724
 AWS IoT API Reference
StartSuiteRun

StartSuiteRun
Service: AWS IoT Core Device Advisor

Starts a Device Advisor test suite run.

Requires permission to access the StartSuiteRun action.

Request Syntax
POST /suiteDefinitions/suiteDefinitionId/suiteRuns HTTP/1.1
Content-type: application/json

{
"suiteDefinitionVersion": "string",
"suiteRunConfiguration": {
"primaryDevice": {
"certificateArn": "string",
"thingArn": "string"
},
"selectedTestList": [ "string" ]
},
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 725)

Suite definition ID of the test suite.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes

Request Body
The request accepts the following data in JSON format.

suiteDefinitionVersion (p. 725)

Suite definition version of the test suite.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

Required: No
suiteRunConfiguration (p. 725)

Suite run configuration.

Type: SuiteRunConfiguration (p. 1040) object

Required: Yes

725
 AWS IoT API Reference
StartSuiteRun

tags (p. 725)

The tags to be attached to the suite run.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"createdAt": number,
"suiteRunArn": "string",
"suiteRunId": "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.

createdAt (p. 726)

Starts a Device Advisor test suite run based on suite create time.

Type: Timestamp
suiteRunArn (p. 726)

Amazon Resource Name (ARN) of the started suite run.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteRunId (p. 726)

Suite Run ID of the started suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Errors
ConflictException

Sends Conflict Exception.

HTTP Status Code: 400

726
 AWS IoT API Reference
StartSuiteRun

InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

727
 AWS IoT API Reference
StopSuiteRun

StopSuiteRun
Service: AWS IoT Core Device Advisor

Stops a Device Advisor test suite run that is currently running.

Requires permission to access the StopSuiteRun action.

Request Syntax
POST /suiteDefinitions/suiteDefinitionId/suiteRuns/suiteRunId/stop HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 728)

Suite definition ID of the test suite run to be stopped.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteRunId (p. 728)

Suite run ID of the test suite run to be stopped.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes

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
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

HTTP Status Code: 404

728
 AWS IoT API Reference
StopSuiteRun

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

729
 AWS IoT API Reference
TagResource

TagResource
Service: AWS IoT Core Device Advisor

Adds to and modifies existing tags of an IoT Device Advisor resource.

Requires permission to access the TagResource action.

Request Syntax
POST /tags/resourceArn HTTP/1.1
Content-type: application/json

{
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

resourceArn (p. 730)

The resource ARN of an IoT Device Advisor resource.

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

Request Body
The request accepts the following data in JSON format.

tags (p. 730)

The tags to be attached to the IoT Device Advisor resource.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

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

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: Yes

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.

730
 AWS IoT API Reference
TagResource

Errors
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

HTTP Status Code: 404

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

731
 AWS IoT API Reference
UntagResource

UntagResource
Service: AWS IoT Core Device Advisor

Removes tags from an IoT Device Advisor resource.

Requires permission to access the UntagResource action.

Request Syntax
DELETE /tags/resourceArn?tagKeys=tagKeys HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceArn (p. 732)

The resource ARN of an IoT Device Advisor resource.

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
tagKeys (p. 732)

List of tag keys to remove from the IoT Device Advisor resource.

Array Members: Minimum number of 0 items. Maximum number of 50 items.

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

Required: Yes

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
InternalServerException

Sends Internal Failure Exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends Resource Not Found Exception.

732
 AWS IoT API Reference
UntagResource

HTTP Status Code: 404

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

733
 AWS IoT API Reference
UpdateSuiteDefinition

UpdateSuiteDefinition
Service: AWS IoT Core Device Advisor

Updates a Device Advisor test suite.

Requires permission to access the UpdateSuiteDefinition action.

Request Syntax
PATCH /suiteDefinitions/suiteDefinitionId HTTP/1.1
Content-type: application/json

{
"suiteDefinitionConfiguration": {
"devicePermissionRoleArn": "string",
"devices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"rootGroup": "string",
"suiteDefinitionName": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 734)

Suite definition ID of the test suite to be updated.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes

Request Body
The request accepts the following data in JSON format.

suiteDefinitionConfiguration (p. 734)

Updates a Device Advisor test suite with suite definition configuration.

Type: SuiteDefinitionConfiguration (p. 1036) object

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

734
 AWS IoT API Reference
UpdateSuiteDefinition

{
"createdAt": number,
"lastUpdatedAt": number,
"suiteDefinitionArn": "string",
"suiteDefinitionId": "string",
"suiteDefinitionName": "string",
"suiteDefinitionVersion": "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.

createdAt (p. 734)

Timestamp of when the test suite was created.

Type: Timestamp
lastUpdatedAt (p. 734)

Timestamp of when the test suite was updated.

Type: Timestamp
suiteDefinitionArn (p. 734)

Amazon Resource Name (ARN) of the updated test suite.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteDefinitionId (p. 734)

Suite definition ID of the updated test suite.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionName (p. 734)

Suite definition name of the updated test suite.

Type: String

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

suiteDefinitionVersion (p. 734)

Suite definition version of the updated test suite.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

Errors
InternalServerException

Sends Internal Failure Exception.

735
 AWS IoT API Reference
AWS IoT Fleet Hub

HTTP Status Code: 500

ValidationException

Sends invalid request exception.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT Fleet Hub

The following actions are supported by AWS IoT Fleet Hub:

• CreateApplication (p. 737)

• DeleteApplication (p. 740)
• DescribeApplication (p. 742)
• ListApplications (p. 746)
• ListTagsForResource (p. 748)
• TagResource (p. 750)
• UntagResource (p. 752)
• UpdateApplication (p. 754)

736
 AWS IoT API Reference
CreateApplication

CreateApplication
Service: AWS IoT Fleet Hub

Creates a Fleet Hub for AWS IoT Device Management web application.

Request Syntax
POST /applications HTTP/1.1
Content-type: application/json

{
"applicationDescription": "string",
"applicationName": "string",
"clientToken": "string",
"roleArn": "string",
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

applicationDescription (p. 737)

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No
applicationName (p. 737)

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: Yes
clientToken (p. 737)

A unique case-sensitive identifier that you can provide to ensure the idempotency of the request.
Don't reuse this client token if a new idempotent request is required.

Type: String

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

737
 AWS IoT API Reference
CreateApplication

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

Required: No
roleArn (p. 737)

The ARN of the role that the web application assumes when it interacts with AWS IoT Core.
Note
The name of the role must be in the form AWSIotFleetHub_random_string .

Type: String

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

Pattern: ^arn:[!-~]+$

Required: Yes
tags (p. 737)

A set of key/value pairs that you can use to manage the web application resource.

Type: String to string map

Map Entries: Maximum number of 50 items.

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

Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

Response Syntax
HTTP/1.1 201
Content-type: application/json

{
"applicationArn": "string",
"applicationId": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 201 response.

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

applicationArn (p. 738)

The ARN of the web application.

Type: String

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

Pattern: ^arn:[!-~]+$

738
 AWS IoT API Reference
CreateApplication

applicationId (p. 738)

The unique Id of the web application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

739
 AWS IoT API Reference
DeleteApplication

DeleteApplication
Service: AWS IoT Fleet Hub

Deletes a Fleet Hub for AWS IoT Device Management web application.

Request Syntax
DELETE /applications/applicationId?clientToken=clientToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId (p. 740)

The unique Id of the web application.

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Required: Yes
clientToken (p. 740)

A unique case-sensitive identifier that you can provide to ensure the idempotency of the request.
Don't reuse this client token if a new idempotent request is required.

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

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

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 204

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

740
 AWS IoT API Reference
DeleteApplication

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

741
 AWS IoT API Reference
DescribeApplication

DescribeApplication
Service: AWS IoT Fleet Hub

Gets information about a Fleet Hub for AWS IoT Device Management web application.

Request Syntax
GET /applications/applicationId HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

applicationId (p. 742)

The unique Id of the web application.

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"applicationArn": "string",
"applicationCreationDate": number,
"applicationDescription": "string",
"applicationId": "string",
"applicationLastUpdateDate": number,
"applicationName": "string",
"applicationState": "string",
"applicationUrl": "string",
"errorMessage": "string",
"roleArn": "string",
"ssoClientId": "string",
"tags": {
"string" : "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.

742
 AWS IoT API Reference
DescribeApplication

applicationArn (p. 742)

The ARN of the web application.

Type: String

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

Pattern: ^arn:[!-~]+$
applicationCreationDate (p. 742)

The date (in Unix epoch time) when the application was created.

Type: Long
applicationDescription (p. 742)

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$
applicationId (p. 742)

The unique Id of the web application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
applicationLastUpdateDate (p. 742)

The date (in Unix epoch time) when the application was last updated.

Type: Long
applicationName (p. 742)

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$
applicationState (p. 742)

The current state of the web application.

Type: String

Valid Values: CREATING | DELETING | ACTIVE | CREATE_FAILED | DELETE_FAILED

applicationUrl (p. 742)

The URL of the web application.

Type: String

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

743
 AWS IoT API Reference
DescribeApplication

Pattern: ^https\://\S+$
errorMessage (p. 742)

A message that explains any failures included in the applicationState response field. This
message explains failures in the CreateApplication and DeleteApplication actions.

Type: String
roleArn (p. 742)

The ARN of the role that the web application assumes when it interacts with AWS IoT Core.

Type: String

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

Pattern: ^arn:[!-~]+$
ssoClientId (p. 742)

The Id of the single sign-on client that you use to authenticate and authorize users on the web
application.

Type: String
tags (p. 742)

A set of key/value pairs that you can use to manage the web application resource.

Type: String to string map

Map Entries: Maximum number of 50 items.

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

Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

744
 AWS IoT API Reference
DescribeApplication

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

745
 AWS IoT API Reference
ListApplications

ListApplications
Service: AWS IoT Fleet Hub

Gets a list of Fleet Hub for AWS IoT Device Management web applications for the current account.

Request Syntax
GET /applications?nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

nextToken (p. 746)

A token used to get the next set of results.

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

Pattern: ^[A-Za-z0-9+/=]+$

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"applicationSummaries": [
{
"applicationCreationDate": number,
"applicationDescription": "string",
"applicationId": "string",
"applicationLastUpdateDate": number,
"applicationName": "string",
"applicationState": "string",
"applicationUrl": "string"
}
],
"nextToken": "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.

applicationSummaries (p. 746)

An array of objects that provide summaries of information about the web applications in the list.

Type: Array of ApplicationSummary (p. 1046) objects

746
 AWS IoT API Reference
ListApplications

nextToken (p. 746)

A token used to get the next set of results.

Type: String

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

Pattern: ^[A-Za-z0-9+/=]+$

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

747
 AWS IoT API Reference
ListTagsForResource

ListTagsForResource
Service: AWS IoT Fleet Hub

Lists the tags for the specified resource.

Request Syntax
GET /tags/resourceArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceArn (p. 748)

The ARN of the resource.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"tags": {
"string" : "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.

tags (p. 748)

The list of tags assigned to the resource.

Type: String to string map

Map Entries: Maximum number of 50 items.

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

Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Value Length Constraints: Minimum length of 1. Maximum length of 256.

748
 AWS IoT API Reference
ListTagsForResource

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

749
 AWS IoT API Reference
TagResource

TagResource
Service: AWS IoT Fleet Hub

Adds to or modifies the tags of the specified resource. Tags are metadata which can be used to manage a
resource.

Request Syntax
POST /tags/resourceArn HTTP/1.1
Content-type: application/json

{
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

resourceArn (p. 750)

The ARN of the resource.

Required: Yes

Request Body
The request accepts the following data in JSON format.

tags (p. 750)

The new or modified tags for the resource.

Type: String to string map

Map Entries: Maximum number of 50 items.

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

Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: Yes

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.

750
 AWS IoT API Reference
TagResource

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

751
 AWS IoT API Reference
UntagResource

UntagResource
Service: AWS IoT Fleet Hub

Removes the specified tags (metadata) from the resource.

Request Syntax
DELETE /tags/resourceArn?tagKeys=tagKeys HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

resourceArn (p. 752)

The ARN of the resource.

Required: Yes
tagKeys (p. 752)

A list of the keys of the tags to be removed from the resource.

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

Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: Yes

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

752
 AWS IoT API Reference
UntagResource

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

753
 AWS IoT API Reference
UpdateApplication

UpdateApplication
Service: AWS IoT Fleet Hub

Updates information about a Fleet Hub for AWS IoT Device Management web application.

Request Syntax
PATCH /applications/applicationId HTTP/1.1
Content-type: application/json

{
"applicationDescription": "string",
"applicationName": "string",
"clientToken": "string"
}

URI Request Parameters

The request uses the following URI parameters.

applicationId (p. 754)

The unique Id of the web application.

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Required: Yes

Request Body
The request accepts the following data in JSON format.

applicationDescription (p. 754)

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No
applicationName (p. 754)

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No

754
 AWS IoT API Reference
UpdateApplication

clientToken (p. 754)

A unique case-sensitive identifier that you can provide to ensure the idempotency of the request.
Don't reuse this client token if a new idempotent request is required.

Type: String

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

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

Required: No

Response Syntax
HTTP/1.1 202

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

Errors
ConflictException

The request conflicts with the current state of the resource.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

755
 AWS IoT API Reference
AWS IoT Secure Tunneling

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT Secure Tunneling

The following actions are supported by AWS IoT Secure Tunneling:

• CloseTunnel (p. 757)

• DescribeTunnel (p. 759)
• ListTagsForResource (p. 761)
• ListTunnels (p. 763)
• OpenTunnel (p. 765)
• TagResource (p. 768)
• UntagResource (p. 770)

756
 AWS IoT API Reference
CloseTunnel

CloseTunnel
Service: AWS IoT Secure Tunneling

Closes a tunnel identified by the unique tunnel id. When a CloseTunnel request is received, we close
the WebSocket connections between the client and proxy server so no data can be transmitted.

Requires permission to access the CloseTunnel action.

Request Syntax
{
"delete": boolean,
"tunnelId": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

delete (p. 757)

When set to true, AWS IoT Secure Tunneling deletes the tunnel data immediately.

Type: Boolean

Required: No
tunnelId (p. 757)

The ID of the tunnel to close.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Required: Yes

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

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

757
 AWS IoT API Reference
CloseTunnel

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

758
 AWS IoT API Reference
DescribeTunnel

DescribeTunnel
Service: AWS IoT Secure Tunneling

Gets information about a tunnel identified by the unique tunnel id.

Requires permission to access the DescribeTunnel action.

Request Syntax
{
"tunnelId": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

tunnelId (p. 759)

The tunnel to describe.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Required: Yes

Response Syntax
{
"tunnel": {
"createdAt": number,
"description": "string",
"destinationConfig": {
"services": [ "string" ],
"thingName": "string"
},
"destinationConnectionState": {
"lastUpdatedAt": number,
"status": "string"
},
"lastUpdatedAt": number,
"sourceConnectionState": {
"lastUpdatedAt": number,
"status": "string"
},
"status": "string",
"tags": [
{
"key": "string",
"value": "string"
}
],
"timeoutConfig": {
"maxLifetimeTimeoutMinutes": number

759
 AWS IoT API Reference
DescribeTunnel

},
"tunnelArn": "string",
"tunnelId": "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.

tunnel (p. 759)

The tunnel being described.

Type: Tunnel (p. 1052) object

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

760
 AWS IoT API Reference
ListTagsForResource

ListTagsForResource
Service: AWS IoT Secure Tunneling

Lists the tags for the specified resource.

Request Syntax
{
"resourceArn": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

resourceArn (p. 761)

The resource ARN.

Type: String

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

Required: Yes

Response Syntax
{
"tags": [
{
"key": "string",
"value": "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.

tags (p. 761)

The tags for the specified resource.

Type: Array of Tag (p. 1050) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

761
 AWS IoT API Reference
ListTagsForResource

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

762
 AWS IoT API Reference
ListTunnels

ListTunnels
Service: AWS IoT Secure Tunneling

List all tunnels for an AWS account. Tunnels are listed by creation time in descending order, newer
tunnels will be listed before older tunnels.

Requires permission to access the ListTunnels action.

Request Syntax
{
"maxResults": number,
"nextToken": "string",
"thingName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

maxResults (p. 763)

The maximum number of results to return at once.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No
nextToken (p. 763)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.

Type: String

Pattern: [a-zA-Z0-9_=-]{1,4096}

Required: No
thingName (p. 763)

The name of the IoT thing associated with the destination device.

Type: String

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

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

Required: No

Response Syntax
{

763
 AWS IoT API Reference
ListTunnels

"nextToken": "string",
"tunnelSummaries": [
{
"createdAt": number,
"description": "string",
"lastUpdatedAt": number,
"status": "string",
"tunnelArn": "string",
"tunnelId": "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.

nextToken (p. 763)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Pattern: [a-zA-Z0-9_=-]{1,4096}
tunnelSummaries (p. 763)

A short description of the tunnels in an AWS account.

Type: Array of TunnelSummary (p. 1054) objects

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

764
 AWS IoT API Reference
OpenTunnel

OpenTunnel
Service: AWS IoT Secure Tunneling

Creates a new tunnel, and returns two client access tokens for clients to use to connect to the AWS IoT
Secure Tunneling proxy server.

Requires permission to access the OpenTunnel action.

Request Syntax
{
"description": "string",
"destinationConfig": {
"services": [ "string" ],
"thingName": "string"
},
"tags": [
{
"key": "string",
"value": "string"
}
],
"timeoutConfig": {
"maxLifetimeTimeoutMinutes": number
}
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

description (p. 765)

A short text description of the tunnel.

Type: String

Pattern: [^\p{C}]{1,2048}

Required: No
destinationConfig (p. 765)

The destination configuration for the OpenTunnel request.

Type: DestinationConfig (p. 1049) object

Required: No
tags (p. 765)

A collection of tag metadata.

Type: Array of Tag (p. 1050) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

Required: No

765
 AWS IoT API Reference
OpenTunnel

timeoutConfig (p. 765)

Timeout configuration for a tunnel.

Type: TimeoutConfig (p. 1051) object

Required: No

Response Syntax
{
"destinationAccessToken": "string",
"sourceAccessToken": "string",
"tunnelArn": "string",
"tunnelId": "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.

destinationAccessToken (p. 766)

The access token the destination local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
sourceAccessToken (p. 766)

The access token the source local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
tunnelArn (p. 766)

The Amazon Resource Name for the tunnel. The tunnel ARN format is
arn:aws:tunnel:<region>:<account-id>:tunnel/<tunnel-id>

Type: String

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

tunnelId (p. 766)

A unique alpha-numeric tunnel ID.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Errors
LimitExceededException

Thrown when a tunnel limit is exceeded.

HTTP Status Code: 400

766
 AWS IoT API Reference
OpenTunnel

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

767
 AWS IoT API Reference
TagResource

TagResource
Service: AWS IoT Secure Tunneling

A resource tag.

Request Syntax
{
"resourceArn": "string",
"tags": [
{
"key": "string",
"value": "string"
}
]
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

resourceArn (p. 768)

The ARN of the resource.

Type: String

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

Required: Yes
tags (p. 768)

The tags for the resource.

Type: Array of Tag (p. 1050) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

Required: Yes

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

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

768
 AWS IoT API Reference
TagResource

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

769
 AWS IoT API Reference
UntagResource

UntagResource
Service: AWS IoT Secure Tunneling

Removes a tag from a resource.

Request Syntax
{
"resourceArn": "string",
"tagKeys": [ "string" ]
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1056).

The request accepts the following data in JSON format.

resourceArn (p. 770)

The resource ARN.

Type: String

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

Required: Yes
tagKeys (p. 770)

The keys of the tags to remove.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 200 items.

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

Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: Yes

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

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

770
 AWS IoT API Reference
UntagResource

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

771
 AWS IoT API Reference

Data Types
The following data types are supported by AWS IoT:

• AbortConfig (p. 782)

• AbortCriteria (p. 783)
• Action (p. 785)
• ActiveViolation (p. 788)
• AddThingsToThingGroupParams (p. 790)
• AggregationType (p. 791)
• AlertTarget (p. 792)
• Allowed (p. 793)
• AssetPropertyTimestamp (p. 794)
• AssetPropertyValue (p. 795)
• AssetPropertyVariant (p. 796)
• AttributePayload (p. 797)
• AuditCheckConfiguration (p. 798)
• AuditCheckDetails (p. 799)
• AuditFinding (p. 801)
• AuditMitigationActionExecutionMetadata (p. 803)
• AuditMitigationActionsTaskMetadata (p. 805)
• AuditMitigationActionsTaskTarget (p. 806)
• AuditNotificationTarget (p. 807)
• AuditSuppression (p. 808)
• AuditTaskMetadata (p. 810)
• AuthInfo (p. 811)
• AuthorizerConfig (p. 812)
• AuthorizerDescription (p. 813)
• AuthorizerSummary (p. 815)
• AuthResult (p. 816)
• AwsJobAbortConfig (p. 817)
• AwsJobAbortCriteria (p. 818)
• AwsJobExecutionsRolloutConfig (p. 820)
• AwsJobExponentialRolloutRate (p. 821)
• AwsJobPresignedUrlConfig (p. 822)
• AwsJobRateIncreaseCriteria (p. 823)
• AwsJobTimeoutConfig (p. 824)
• Behavior (p. 825)
• BehaviorCriteria (p. 827)
• BehaviorModelTrainingSummary (p. 829)
• BillingGroupMetadata (p. 831)
• BillingGroupProperties (p. 832)
• Bucket (p. 833)

772
 AWS IoT API Reference

• BucketsAggregationType (p. 834)

• CACertificate (p. 835)
• CACertificateDescription (p. 836)
• Certificate (p. 838)
• CertificateDescription (p. 840)
• CertificateValidity (p. 843)
• CloudwatchAlarmAction (p. 844)
• CloudwatchLogsAction (p. 845)
• CloudwatchMetricAction (p. 846)
• CodeSigning (p. 848)
• CodeSigningCertificateChain (p. 849)
• CodeSigningSignature (p. 850)
• Configuration (p. 851)
• CustomCodeSigning (p. 852)
• Denied (p. 853)
• Destination (p. 854)
• DetectMitigationActionExecution (p. 855)
• DetectMitigationActionsTaskStatistics (p. 857)
• DetectMitigationActionsTaskSummary (p. 858)
• DetectMitigationActionsTaskTarget (p. 860)
• DomainConfigurationSummary (p. 861)
• DynamoDBAction (p. 862)
• DynamoDBv2Action (p. 864)
• EffectivePolicy (p. 865)
• ElasticsearchAction (p. 866)
• EnableIoTLoggingParams (p. 867)
• ErrorInfo (p. 868)
• ExplicitDeny (p. 869)
• ExponentialRolloutRate (p. 870)
• Field (p. 871)
• FileLocation (p. 872)
• FirehoseAction (p. 873)
• FleetMetricNameAndArn (p. 874)
• GroupNameAndArn (p. 875)
• HttpAction (p. 876)
• HttpActionHeader (p. 878)
• HttpAuthorization (p. 879)
• HttpContext (p. 880)
• HttpUrlDestinationConfiguration (p. 881)
• HttpUrlDestinationProperties (p. 882)
• HttpUrlDestinationSummary (p. 883)
• ImplicitDeny (p. 884)
• IotAnalyticsAction (p. 885)
• IotEventsAction (p. 886)
• IotSiteWiseAction (p. 888)

773
 AWS IoT API Reference

• Job (p. 889)

• JobExecution (p. 893)
• JobExecutionsRolloutConfig (p. 895)
• JobExecutionStatusDetails (p. 896)
• JobExecutionSummary (p. 897)
• JobExecutionSummaryForJob (p. 899)
• JobExecutionSummaryForThing (p. 900)
• JobProcessDetails (p. 901)
• JobSummary (p. 903)
• JobTemplateSummary (p. 905)
• KafkaAction (p. 907)
• KeyPair (p. 908)
• KinesisAction (p. 909)
• LambdaAction (p. 910)
• LoggingOptionsPayload (p. 911)
• LogTarget (p. 912)
• LogTargetConfiguration (p. 913)
• MachineLearningDetectionConfig (p. 914)
• MetricDimension (p. 915)
• MetricToRetain (p. 916)
• MetricValue (p. 917)
• MitigationAction (p. 919)
• MitigationActionIdentifier (p. 920)
• MitigationActionParams (p. 921)
• MqttContext (p. 923)
• NonCompliantResource (p. 924)
• OTAUpdateFile (p. 925)
• OTAUpdateInfo (p. 927)
• OTAUpdateSummary (p. 930)
• OutgoingCertificate (p. 931)
• PercentPair (p. 933)
• Policy (p. 934)
• PolicyVersion (p. 935)
• PolicyVersionIdentifier (p. 936)
• PresignedUrlConfig (p. 937)
• ProvisioningHook (p. 938)
• ProvisioningTemplateSummary (p. 939)
• ProvisioningTemplateVersionSummary (p. 941)
• PublishFindingToSnsParams (p. 942)
• PutAssetPropertyValueEntry (p. 943)
• PutItemInput (p. 945)
• RateIncreaseCriteria (p. 946)
• RegistrationConfig (p. 947)
• RelatedResource (p. 948)
• ReplaceDefaultPolicyVersionParams (p. 949)

774
 AWS IoT API Reference

• RepublishAction (p. 950)

• ResourceIdentifier (p. 951)
• RoleAliasDescription (p. 953)
• S3Action (p. 955)
• S3Destination (p. 956)
• S3Location (p. 957)
• SalesforceAction (p. 958)
• ScheduledAuditMetadata (p. 959)
• SecurityProfileIdentifier (p. 961)
• SecurityProfileTarget (p. 962)
• SecurityProfileTargetMapping (p. 963)
• ServerCertificateSummary (p. 964)
• SigningProfileParameter (p. 965)
• SigV4Authorization (p. 966)
• SnsAction (p. 967)
• SqsAction (p. 968)
• StartSigningJobParameter (p. 969)
• StatisticalThreshold (p. 970)
• Statistics (p. 971)
• StepFunctionsAction (p. 973)
• Stream (p. 974)
• StreamFile (p. 975)
• StreamInfo (p. 976)
• StreamSummary (p. 978)
• Tag (p. 979)
• TaskStatistics (p. 980)
• TaskStatisticsForAuditCheck (p. 982)
• TermsAggregation (p. 983)
• ThingAttribute (p. 984)
• ThingConnectivity (p. 986)
• ThingDocument (p. 987)
• ThingGroupDocument (p. 989)
• ThingGroupIndexingConfiguration (p. 991)
• ThingGroupMetadata (p. 992)
• ThingGroupProperties (p. 993)
• ThingIndexingConfiguration (p. 994)
• ThingTypeDefinition (p. 996)
• ThingTypeMetadata (p. 997)
• ThingTypeProperties (p. 998)
• TimeoutConfig (p. 999)
• TimestreamAction (p. 1000)
• TimestreamDimension (p. 1002)
• TimestreamTimestamp (p. 1003)
• TlsContext (p. 1004)
• TopicRule (p. 1005)
• TopicRuleDestination (p. 1007)

775
 AWS IoT API Reference

• TopicRuleDestinationConfiguration (p. 1009)

• TopicRuleDestinationSummary (p. 1010)
• TopicRuleListItem (p. 1012)
• TopicRulePayload (p. 1013)
• TransferData (p. 1015)
• UpdateCACertificateParams (p. 1016)
• UpdateDeviceCertificateParams (p. 1017)
• ValidationError (p. 1018)
• ViolationEvent (p. 1019)
• ViolationEventAdditionalInfo (p. 1021)
• ViolationEventOccurrenceRange (p. 1022)
• VpcDestinationConfiguration (p. 1023)
• VpcDestinationProperties (p. 1024)
• VpcDestinationSummary (p. 1025)

The following data types are supported by AWS IoT data:

• RetainedMessageSummary (p. 1026)

The following data types are supported by AWS IoT jobs data:

• JobExecution (p. 1028)

• JobExecutionState (p. 1031)
• JobExecutionSummary (p. 1032)

The following data types are supported by AWS IoT Core Device Advisor:

• DeviceUnderTest (p. 1034)

• GroupResult (p. 1035)
• SuiteDefinitionConfiguration (p. 1036)
• SuiteDefinitionInformation (p. 1038)
• SuiteRunConfiguration (p. 1040)
• SuiteRunInformation (p. 1041)
• TestCaseRun (p. 1043)
• TestResult (p. 1045)

The following data types are supported by AWS IoT Fleet Hub:

• ApplicationSummary (p. 1046)

The following data types are supported by AWS IoT Secure Tunneling:

• ConnectionState (p. 1048)

• DestinationConfig (p. 1049)
• Tag (p. 1050)
• TimeoutConfig (p. 1051)
• Tunnel (p. 1052)
• TunnelSummary (p. 1054)

776
 AWS IoT API Reference
AWS IoT

AWS IoT
The following data types are supported by AWS IoT:

• AbortConfig (p. 782)

• AbortCriteria (p. 783)
• Action (p. 785)
• ActiveViolation (p. 788)
• AddThingsToThingGroupParams (p. 790)
• AggregationType (p. 791)
• AlertTarget (p. 792)
• Allowed (p. 793)
• AssetPropertyTimestamp (p. 794)
• AssetPropertyValue (p. 795)
• AssetPropertyVariant (p. 796)
• AttributePayload (p. 797)
• AuditCheckConfiguration (p. 798)
• AuditCheckDetails (p. 799)
• AuditFinding (p. 801)
• AuditMitigationActionExecutionMetadata (p. 803)
• AuditMitigationActionsTaskMetadata (p. 805)
• AuditMitigationActionsTaskTarget (p. 806)
• AuditNotificationTarget (p. 807)
• AuditSuppression (p. 808)
• AuditTaskMetadata (p. 810)
• AuthInfo (p. 811)
• AuthorizerConfig (p. 812)
• AuthorizerDescription (p. 813)
• AuthorizerSummary (p. 815)
• AuthResult (p. 816)
• AwsJobAbortConfig (p. 817)
• AwsJobAbortCriteria (p. 818)
• AwsJobExecutionsRolloutConfig (p. 820)
• AwsJobExponentialRolloutRate (p. 821)
• AwsJobPresignedUrlConfig (p. 822)
• AwsJobRateIncreaseCriteria (p. 823)
• AwsJobTimeoutConfig (p. 824)
• Behavior (p. 825)
• BehaviorCriteria (p. 827)
• BehaviorModelTrainingSummary (p. 829)
• BillingGroupMetadata (p. 831)
• BillingGroupProperties (p. 832)
• Bucket (p. 833)
• BucketsAggregationType (p. 834)
• CACertificate (p. 835)
• CACertificateDescription (p. 836)

777
 AWS IoT API Reference
AWS IoT

• Certificate (p. 838)

• CertificateDescription (p. 840)
• CertificateValidity (p. 843)
• CloudwatchAlarmAction (p. 844)
• CloudwatchLogsAction (p. 845)
• CloudwatchMetricAction (p. 846)
• CodeSigning (p. 848)
• CodeSigningCertificateChain (p. 849)
• CodeSigningSignature (p. 850)
• Configuration (p. 851)
• CustomCodeSigning (p. 852)
• Denied (p. 853)
• Destination (p. 854)
• DetectMitigationActionExecution (p. 855)
• DetectMitigationActionsTaskStatistics (p. 857)
• DetectMitigationActionsTaskSummary (p. 858)
• DetectMitigationActionsTaskTarget (p. 860)
• DomainConfigurationSummary (p. 861)
• DynamoDBAction (p. 862)
• DynamoDBv2Action (p. 864)
• EffectivePolicy (p. 865)
• ElasticsearchAction (p. 866)
• EnableIoTLoggingParams (p. 867)
• ErrorInfo (p. 868)
• ExplicitDeny (p. 869)
• ExponentialRolloutRate (p. 870)
• Field (p. 871)
• FileLocation (p. 872)
• FirehoseAction (p. 873)
• FleetMetricNameAndArn (p. 874)
• GroupNameAndArn (p. 875)
• HttpAction (p. 876)
• HttpActionHeader (p. 878)
• HttpAuthorization (p. 879)
• HttpContext (p. 880)
• HttpUrlDestinationConfiguration (p. 881)
• HttpUrlDestinationProperties (p. 882)
• HttpUrlDestinationSummary (p. 883)
• ImplicitDeny (p. 884)
• IotAnalyticsAction (p. 885)
• IotEventsAction (p. 886)
• IotSiteWiseAction (p. 888)
• Job (p. 889)
• JobExecution (p. 893)
• JobExecutionsRolloutConfig (p. 895)
• JobExecutionStatusDetails (p. 896)

778
 AWS IoT API Reference
AWS IoT

• JobExecutionSummary (p. 897)

• JobExecutionSummaryForJob (p. 899)
• JobExecutionSummaryForThing (p. 900)
• JobProcessDetails (p. 901)
• JobSummary (p. 903)
• JobTemplateSummary (p. 905)
• KafkaAction (p. 907)
• KeyPair (p. 908)
• KinesisAction (p. 909)
• LambdaAction (p. 910)
• LoggingOptionsPayload (p. 911)
• LogTarget (p. 912)
• LogTargetConfiguration (p. 913)
• MachineLearningDetectionConfig (p. 914)
• MetricDimension (p. 915)
• MetricToRetain (p. 916)
• MetricValue (p. 917)
• MitigationAction (p. 919)
• MitigationActionIdentifier (p. 920)
• MitigationActionParams (p. 921)
• MqttContext (p. 923)
• NonCompliantResource (p. 924)
• OTAUpdateFile (p. 925)
• OTAUpdateInfo (p. 927)
• OTAUpdateSummary (p. 930)
• OutgoingCertificate (p. 931)
• PercentPair (p. 933)
• Policy (p. 934)
• PolicyVersion (p. 935)
• PolicyVersionIdentifier (p. 936)
• PresignedUrlConfig (p. 937)
• ProvisioningHook (p. 938)
• ProvisioningTemplateSummary (p. 939)
• ProvisioningTemplateVersionSummary (p. 941)
• PublishFindingToSnsParams (p. 942)
• PutAssetPropertyValueEntry (p. 943)
• PutItemInput (p. 945)
• RateIncreaseCriteria (p. 946)
• RegistrationConfig (p. 947)
• RelatedResource (p. 948)
• ReplaceDefaultPolicyVersionParams (p. 949)
• RepublishAction (p. 950)
• ResourceIdentifier (p. 951)
• RoleAliasDescription (p. 953)
• S3Action (p. 955)
• S3Destination (p. 956)

779
 AWS IoT API Reference
AWS IoT

• S3Location (p. 957)

• SalesforceAction (p. 958)
• ScheduledAuditMetadata (p. 959)
• SecurityProfileIdentifier (p. 961)
• SecurityProfileTarget (p. 962)
• SecurityProfileTargetMapping (p. 963)
• ServerCertificateSummary (p. 964)
• SigningProfileParameter (p. 965)
• SigV4Authorization (p. 966)
• SnsAction (p. 967)
• SqsAction (p. 968)
• StartSigningJobParameter (p. 969)
• StatisticalThreshold (p. 970)
• Statistics (p. 971)
• StepFunctionsAction (p. 973)
• Stream (p. 974)
• StreamFile (p. 975)
• StreamInfo (p. 976)
• StreamSummary (p. 978)
• Tag (p. 979)
• TaskStatistics (p. 980)
• TaskStatisticsForAuditCheck (p. 982)
• TermsAggregation (p. 983)
• ThingAttribute (p. 984)
• ThingConnectivity (p. 986)
• ThingDocument (p. 987)
• ThingGroupDocument (p. 989)
• ThingGroupIndexingConfiguration (p. 991)
• ThingGroupMetadata (p. 992)
• ThingGroupProperties (p. 993)
• ThingIndexingConfiguration (p. 994)
• ThingTypeDefinition (p. 996)
• ThingTypeMetadata (p. 997)
• ThingTypeProperties (p. 998)
• TimeoutConfig (p. 999)
• TimestreamAction (p. 1000)
• TimestreamDimension (p. 1002)
• TimestreamTimestamp (p. 1003)
• TlsContext (p. 1004)
• TopicRule (p. 1005)
• TopicRuleDestination (p. 1007)
• TopicRuleDestinationConfiguration (p. 1009)
• TopicRuleDestinationSummary (p. 1010)
• TopicRuleListItem (p. 1012)
• TopicRulePayload (p. 1013)
• TransferData (p. 1015)

780
 AWS IoT API Reference
AWS IoT

• UpdateCACertificateParams (p. 1016)

• UpdateDeviceCertificateParams (p. 1017)
• ValidationError (p. 1018)
• ViolationEvent (p. 1019)
• ViolationEventAdditionalInfo (p. 1021)
• ViolationEventOccurrenceRange (p. 1022)
• VpcDestinationConfiguration (p. 1023)
• VpcDestinationProperties (p. 1024)
• VpcDestinationSummary (p. 1025)

781
 AWS IoT API Reference
AbortConfig

AbortConfig
Service: AWS IoT

The criteria that determine when and how a job abort takes place.

Contents
criteriaList

The list of criteria that determine when and how to abort the job.

Type: Array of AbortCriteria (p. 783) objects

Array Members: Minimum number of 1 item.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

782
 AWS IoT API Reference
AbortCriteria

AbortCriteria
Service: AWS IoT

The criteria that determine when and how a job abort takes place.

Contents
action

The type of job action to take to initiate the job abort.

Type: String

Valid Values: CANCEL

Required: Yes
failureType

The type of job execution failures that can initiate a job abort.

Type: String

Valid Values: FAILED | REJECTED | TIMED_OUT | ALL

Required: Yes
minNumberOfExecutedThings

The minimum number of things which must receive job execution notifications before the job can be
aborted.

Type: Integer

Valid Range: Minimum value of 1.

Required: Yes
thresholdPercentage

The minimum percentage of job execution failures that must occur to initiate the job abort.

AWS IoT Core supports up to two digits after the decimal (for example, 10.9 and 10.99, but not
10.999).

Type: Double

Valid Range: Maximum value of 100.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

783
AWS IoT API Reference
AbortCriteria

784
 AWS IoT API Reference
Action

Action
Service: AWS IoT

Describes the actions associated with a rule.

Contents
cloudwatchAlarm

Change the state of a CloudWatch alarm.

Type: CloudwatchAlarmAction (p. 844) object

Required: No
cloudwatchLogs

Send data to CloudWatch Logs.

Type: CloudwatchLogsAction (p. 845) object

Required: No
cloudwatchMetric

Capture a CloudWatch metric.

Type: CloudwatchMetricAction (p. 846) object

Required: No
dynamoDB

Write to a DynamoDB table.

Type: DynamoDBAction (p. 862) object

Required: No
dynamoDBv2

Write to a DynamoDB table. This is a new version of the DynamoDB action. It allows you to write
each attribute in an MQTT message payload into a separate DynamoDB column.

Type: DynamoDBv2Action (p. 864) object

Required: No
elasticsearch

Write data to an Amazon OpenSearch Service domain.

Type: ElasticsearchAction (p. 866) object

Required: No
firehose

Write to an Amazon Kinesis Firehose stream.

Type: FirehoseAction (p. 873) object

Required: No

785
 AWS IoT API Reference
Action

http

Send data to an HTTPS endpoint.

Type: HttpAction (p. 876) object

Required: No
iotAnalytics

Sends message data to an AWS IoT Analytics channel.

Type: IotAnalyticsAction (p. 885) object

Required: No
iotEvents

Sends an input to an AWS IoT Events detector.

Type: IotEventsAction (p. 886) object

Required: No
iotSiteWise

Sends data from the MQTT message that triggered the rule to AWS IoT SiteWise asset properties.

Type: IotSiteWiseAction (p. 888) object

Required: No
kafka

Send messages to an Amazon Managed Streaming for Apache Kafka (Amazon MSK) or self-managed
Apache Kafka cluster.

Type: KafkaAction (p. 907) object

Required: No
kinesis

Write data to an Amazon Kinesis stream.

Type: KinesisAction (p. 909) object

Required: No
lambda

Invoke a Lambda function.

Type: LambdaAction (p. 910) object

Required: No
republish

Publish to another MQTT topic.

Type: RepublishAction (p. 950) object

Required: No
s3

Write to an Amazon S3 bucket.

786
 AWS IoT API Reference
Action

Type: S3Action (p. 955) object

Required: No
salesforce

Send a message to a Salesforce IoT Cloud Input Stream.

Type: SalesforceAction (p. 958) object

Required: No
sns

Publish to an Amazon SNS topic.

Type: SnsAction (p. 967) object

Required: No
sqs

Publish to an Amazon SQS queue.

Type: SqsAction (p. 968) object

Required: No
stepFunctions

Starts execution of a Step Functions state machine.

Type: StepFunctionsAction (p. 973) object

Required: No
timestream

The Timestream rule action writes attributes (measures) from an MQTT message into an Amazon
Timestream table. For more information, see the Timestream topic rule action documentation.

Type: TimestreamAction (p. 1000) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

787
 AWS IoT API Reference
ActiveViolation

ActiveViolation
Service: AWS IoT

Information about an active Device Defender security profile behavior violation.

Contents
behavior

The behavior that is being violated.

Type: Behavior (p. 825) object

Required: No
lastViolationTime

The time the most recent violation occurred.

Type: Timestamp

Required: No
lastViolationValue

The value of the metric (the measurement) that caused the most recent violation.

Type: MetricValue (p. 917) object

Required: No
securityProfileName

The security profile with the behavior is in violation.

Type: String

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

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

Required: No
thingName

The name of the thing responsible for the active violation.

Type: String

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

Required: No
violationEventAdditionalInfo

The details of a violation event.

Type: ViolationEventAdditionalInfo (p. 1021) object

Required: No
violationId

The ID of the active violation.

788
 AWS IoT API Reference
ActiveViolation

Type: String

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

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

Required: No
violationStartTime

The time the violation started.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

789
 AWS IoT API Reference
AddThingsToThingGroupParams

AddThingsToThingGroupParams
Service: AWS IoT

Parameters used when defining a mitigation action that move a set of things to a thing group.

Contents
overrideDynamicGroups

Specifies if this mitigation action can move the things that triggered the mitigation action even if
they are part of one or more dynamic thing groups.

Type: Boolean

Required: No
thingGroupNames

The list of groups to which you want to add the things that triggered the mitigation action. You can
add a thing to a maximum of 10 groups, but you can't add a thing to more than one group in the
same hierarchy.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 10 items.

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

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

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

790
 AWS IoT API Reference
AggregationType

AggregationType
Service: AWS IoT

The type of aggregation queries.

Contents
name

The name of the aggregation type.

Type: String

Valid Values: Statistics | Percentiles | Cardinality

Required: Yes
values

A list of the values of aggregation types.

Type: Array of strings

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

791
 AWS IoT API Reference
AlertTarget

AlertTarget
Service: AWS IoT

A structure containing the alert target ARN and the role ARN.

Contents
alertTargetArn

The Amazon Resource Name (ARN) of the notification target to which alerts are sent.

Type: String

Required: Yes
roleArn

The ARN of the role that grants permission to send alerts to the notification target.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

792
 AWS IoT API Reference
Allowed

Allowed
Service: AWS IoT

Contains information that allowed the authorization.

Contents
policies

A list of policies that allowed the authentication.

Type: Array of Policy (p. 934) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

793
 AWS IoT API Reference
AssetPropertyTimestamp

AssetPropertyTimestamp
Service: AWS IoT

An asset property timestamp entry containing the following information.

Contents
offsetInNanos

Optional. A string that contains the nanosecond time offset. Accepts substitution templates.

Type: String

Required: No
timeInSeconds

A string that contains the time in seconds since epoch. Accepts substitution templates.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

794
 AWS IoT API Reference
AssetPropertyValue

AssetPropertyValue
Service: AWS IoT

An asset property value entry containing the following information.

Contents
quality

Optional. A string that describes the quality of the value. Accepts substitution templates. Must be
GOOD, BAD, or UNCERTAIN.

Type: String

Required: No
timestamp

The asset property value timestamp.

Type: AssetPropertyTimestamp (p. 794) object

Required: Yes
value

The value of the asset property.

Type: AssetPropertyVariant (p. 796) object

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

795
 AWS IoT API Reference
AssetPropertyVariant

AssetPropertyVariant
Service: AWS IoT

Contains an asset property value (of a single type).

Contents
booleanValue

Optional. A string that contains the boolean value (true or false) of the value entry. Accepts
substitution templates.

Type: String

Required: No
doubleValue

Optional. A string that contains the double value of the value entry. Accepts substitution templates.

Type: String

Required: No
integerValue

Optional. A string that contains the integer value of the value entry. Accepts substitution templates.

Type: String

Required: No
stringValue

Optional. The string value of the value entry. Accepts substitution templates.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

796
 AWS IoT API Reference
AttributePayload

AttributePayload
Service: AWS IoT

The attribute payload.

Contents
attributes

A JSON string containing up to three key-value pair in JSON format. For example:

{\"attributes\":{\"string1\":\"string2\"}}

Type: String to string map

Key Length Constraints: Maximum length of 128.

Key Pattern: [a-zA-Z0-9_.,@/:#-]+

Value Length Constraints: Maximum length of 800.

Value Pattern: [a-zA-Z0-9_.,@/:#-]*

Required: No
merge

Specifies whether the list of attributes provided in the AttributePayload is merged with the
attributes stored in the registry, instead of overwriting them.

To remove an attribute, call UpdateThing with an empty attribute value.

Note
The merge attribute is only valid when calling UpdateThing or UpdateThingGroup.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

797
 AWS IoT API Reference
AuditCheckConfiguration

AuditCheckConfiguration
Service: AWS IoT

Which audit checks are enabled and disabled for this account.

Contents
enabled

True if this audit check is enabled for this account.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

798
 AWS IoT API Reference
AuditCheckDetails

AuditCheckDetails
Service: AWS IoT

Information about the audit check.

Contents
checkCompliant

True if the check is complete and found all resources compliant.

Type: Boolean

Required: No
checkRunStatus

The completion status of this check. One of "IN_PROGRESS", "WAITING_FOR_DATA_COLLECTION",

"CANCELED", "COMPLETED_COMPLIANT", "COMPLETED_NON_COMPLIANT", or "FAILED".

Type: String

Valid Values: IN_PROGRESS | WAITING_FOR_DATA_COLLECTION | CANCELED |

COMPLETED_COMPLIANT | COMPLETED_NON_COMPLIANT | FAILED

Required: No
errorCode

The code of any error encountered when this check is performed during this audit. One of
"INSUFFICIENT_PERMISSIONS" or "AUDIT_CHECK_DISABLED".

Type: String

Required: No
message

The message associated with any error encountered when this check is performed during this audit.

Type: String

Length Constraints: Maximum length of 2048.

Required: No
nonCompliantResourcesCount

The number of resources that were found noncompliant during the check.

Type: Long

Required: No
suppressedNonCompliantResourcesCount

Describes how many of the non-compliant resources created during the evaluation of an audit check
were marked as suppressed.

Type: Long

Required: No

799
 AWS IoT API Reference
AuditCheckDetails

totalResourcesCount

The number of resources on which the check was performed.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

800
 AWS IoT API Reference
AuditFinding

AuditFinding
Service: AWS IoT

The findings (results) of the audit.

Contents
checkName

The audit check that generated this result.

Type: String

Required: No
findingId

A unique identifier for this set of audit findings. This identifier is used to apply mitigation tasks to
one or more sets of findings.

Type: String

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

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

Required: No
findingTime

The time the result (finding) was discovered.

Type: Timestamp

Required: No
isSuppressed

Indicates whether the audit finding was suppressed or not during reporting.

Type: Boolean

Required: No
nonCompliantResource

The resource that was found to be noncompliant with the audit check.

Type: NonCompliantResource (p. 924) object

Required: No
reasonForNonCompliance

The reason the resource was noncompliant.

Type: String

Required: No
reasonForNonComplianceCode

A code that indicates the reason that the resource was noncompliant.

Type: String

801
 AWS IoT API Reference
AuditFinding

Required: No
relatedResources

The list of related resources.

Type: Array of RelatedResource (p. 948) objects

Required: No
severity

The severity of the result (finding).

Type: String

Valid Values: CRITICAL | HIGH | MEDIUM | LOW

Required: No
taskId

The ID of the audit that generated this result (finding).

Type: String

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

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

Required: No
taskStartTime

The time the audit started.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

802
 AWS IoT API Reference
AuditMitigationActionExecutionMetadata

AuditMitigationActionExecutionMetadata
Service: AWS IoT

Returned by ListAuditMitigationActionsTask, this object contains information that describes a mitigation

action that has been started.

Contents
actionId

The unique identifier for the mitigation action being applied by the task.

Type: String

Required: No
actionName

The friendly name of the mitigation action being applied by the task.

Type: String

Length Constraints: Maximum length of 128.

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

Required: No
endTime

The date and time when the task was completed or canceled. Blank if the task is still running.

Type: Timestamp

Required: No
errorCode

If an error occurred, the code that indicates which type of error occurred.

Type: String

Required: No
findingId

The unique identifier for the findings to which the task and associated mitigation action are applied.

Type: String

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

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

Required: No
message

If an error occurred, a message that describes the error.

Type: String

Length Constraints: Maximum length of 2048.

803
 AWS IoT API Reference
AuditMitigationActionExecutionMetadata

Required: No
startTime

The date and time when the task was started.

Type: Timestamp

Required: No
status

The current status of the task being executed.

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED | SKIPPED | PENDING

Required: No
taskId

The unique identifier for the task that applies the mitigation action.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

804
 AWS IoT API Reference
AuditMitigationActionsTaskMetadata

AuditMitigationActionsTaskMetadata
Service: AWS IoT

Information about an audit mitigation actions task that is returned by

ListAuditMitigationActionsTasks.

Contents
startTime

The time at which the audit mitigation actions task was started.

Type: Timestamp

Required: No
taskId

The unique identifier for the task.

Type: String

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

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

Required: No
taskStatus

The current state of the audit mitigation actions task.

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

805
 AWS IoT API Reference
AuditMitigationActionsTaskTarget

AuditMitigationActionsTaskTarget
Service: AWS IoT

Used in MitigationActionParams, this information identifies the target findings to which the mitigation
actions are applied. Only one entry appears.

Contents
auditCheckToReasonCodeFilter

Specifies a filter in the form of an audit check and set of reason codes that identify the findings from
the audit to which the audit mitigation actions task apply.

Type: String to array of strings map

Array Members: Minimum number of 1 item. Maximum number of 25 items.

Required: No
auditTaskId

If the task will apply a mitigation action to findings from a specific audit, this value uniquely
identifies the audit.

Type: String

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

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

Required: No
findingIds

If the task will apply a mitigation action to one or more listed findings, this value uniquely identifies
those findings.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 25 items.

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

806
 AWS IoT API Reference
AuditNotificationTarget

AuditNotificationTarget
Service: AWS IoT

Information about the targets to which audit notifications are sent.

Contents
enabled

True if notifications to the target are enabled.

Type: Boolean

Required: No
roleArn

The ARN of the role that grants permission to send notifications to the target.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
targetArn

The ARN of the target (SNS topic) to which audit notifications are sent.

Type: String

Length Constraints: Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

807
 AWS IoT API Reference
AuditSuppression

AuditSuppression
Service: AWS IoT

Filters out specific findings of a Device Defender audit.

Contents
checkName

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: Yes
description

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No
expirationDate

The expiration date (epoch timestamp in seconds) that you want the suppression to adhere to.

Type: Timestamp

Required: No
resourceIdentifier

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: Yes
suppressIndefinitely

Indicates whether a suppression should exist indefinitely or not.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2

808
 AWS IoT API Reference
AuditSuppression

• AWS SDK for Ruby V3

809
 AWS IoT API Reference
AuditTaskMetadata

AuditTaskMetadata
Service: AWS IoT

The audits that were performed.

Contents
taskId

The ID of this audit.

Type: String

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

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

Required: No
taskStatus

The status of this audit. One of "IN_PROGRESS", "COMPLETED", "FAILED", or "CANCELED".

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

Required: No
taskType

The type of this audit. One of "ON_DEMAND_AUDIT_TASK" or "SCHEDULED_AUDIT_TASK".

Type: String

Valid Values: ON_DEMAND_AUDIT_TASK | SCHEDULED_AUDIT_TASK

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

810
 AWS IoT API Reference
AuthInfo

AuthInfo
Service: AWS IoT

A collection of authorization information.

Contents
actionType

The type of action for which the principal is being authorized.

Type: String

Valid Values: PUBLISH | SUBSCRIBE | RECEIVE | CONNECT

Required: No
resources

The resources for which the principal is being authorized to perform the specified action.

Type: Array of strings

Length Constraints: Maximum length of 2048.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

811
 AWS IoT API Reference
AuthorizerConfig

AuthorizerConfig
Service: AWS IoT

An object that specifies the authorization service for a domain.

Contents
allowAuthorizerOverride

A Boolean that specifies whether the domain configuration's authorization service can be
overridden.

Type: Boolean

Required: No
defaultAuthorizerName

The name of the authorization service for a domain configuration.

Type: String

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

Pattern: [\w=,@-]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

812
 AWS IoT API Reference
AuthorizerDescription

AuthorizerDescription
Service: AWS IoT

The authorizer description.

Contents
authorizerArn

The authorizer ARN.

Type: String

Length Constraints: Maximum length of 2048.

Required: No
authorizerFunctionArn

The authorizer's Lambda function ARN.

Type: String

Length Constraints: Maximum length of 2048.

Required: No
authorizerName

The authorizer name.

Type: String

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

Pattern: [\w=,@-]+

Required: No
creationDate

The UNIX timestamp of when the authorizer was created.

Type: Timestamp

Required: No
lastModifiedDate

The UNIX timestamp of when the authorizer was last updated.

Type: Timestamp

Required: No
signingDisabled

Specifies whether AWS IoT validates the token signature in an authorization request.

Type: Boolean

Required: No
status

The status of the authorizer.

813
 AWS IoT API Reference
AuthorizerDescription

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
tokenKeyName

The key used to extract the token from the HTTP headers.

Type: String

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

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

Required: No
tokenSigningPublicKeys

The public keys used to validate the token signature returned by your custom authentication service.

Type: String to string map

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

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

Value Length Constraints: Maximum length of 5120.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

814
 AWS IoT API Reference
AuthorizerSummary

AuthorizerSummary
Service: AWS IoT

The authorizer summary.

Contents
authorizerArn

The authorizer ARN.

Type: String

Length Constraints: Maximum length of 2048.

Required: No
authorizerName

The authorizer name.

Type: String

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

Pattern: [\w=,@-]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

815
 AWS IoT API Reference
AuthResult

AuthResult
Service: AWS IoT

The authorizer result.

Contents
allowed

The policies and statements that allowed the specified action.

Type: Allowed (p. 793) object

Required: No
authDecision

The final authorization decision of this scenario. Multiple statements are taken into account when
determining the authorization decision. An explicit deny statement can override multiple allow
statements.

Type: String

Valid Values: ALLOWED | EXPLICIT_DENY | IMPLICIT_DENY

Required: No
authInfo

Authorization information.

Type: AuthInfo (p. 811) object

Required: No
denied

The policies and statements that denied the specified action.

Type: Denied (p. 853) object

Required: No
missingContextValues

Contains any missing context values found while evaluating policy.

Type: Array of strings

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

816
 AWS IoT API Reference
AwsJobAbortConfig

AwsJobAbortConfig
Service: AWS IoT

The criteria that determine when and how a job abort takes place.

Contents
abortCriteriaList

The list of criteria that determine when and how to abort the job.

Type: Array of AwsJobAbortCriteria (p. 818) objects

Array Members: Minimum number of 1 item.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

817
 AWS IoT API Reference
AwsJobAbortCriteria

AwsJobAbortCriteria
Service: AWS IoT

The criteria that determine when and how a job abort takes place.

Contents
action

The type of job action to take to initiate the job abort.

Type: String

Valid Values: CANCEL

Required: Yes
failureType

The type of job execution failures that can initiate a job abort.

Type: String

Valid Values: FAILED | REJECTED | TIMED_OUT | ALL

Required: Yes
minNumberOfExecutedThings

The minimum number of things which must receive job execution notifications before the job can be
aborted.

Type: Integer

Valid Range: Minimum value of 1.

Required: Yes
thresholdPercentage

The minimum percentage of job execution failures that must occur to initiate the job abort.

AWS IoT Core supports up to two digits after the decimal (for example, 10.9 and 10.99, but not
10.999).

Type: Double

Valid Range: Maximum value of 100.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

818
AWS IoT API Reference
AwsJobAbortCriteria

819
 AWS IoT API Reference
AwsJobExecutionsRolloutConfig

AwsJobExecutionsRolloutConfig
Service: AWS IoT

Configuration for the rollout of OTA updates.

Contents
exponentialRate

The rate of increase for a job rollout. This parameter allows you to define an exponential rate
increase for a job rollout.

Type: AwsJobExponentialRolloutRate (p. 821) object

Required: No
maximumPerMinute

The maximum number of OTA update job executions started per minute.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

820
 AWS IoT API Reference
AwsJobExponentialRolloutRate

AwsJobExponentialRolloutRate
Service: AWS IoT

The rate of increase for a job rollout. This parameter allows you to define an exponential rate increase
for a job rollout.

Contents
baseRatePerMinute

The minimum number of things that will be notified of a pending job, per minute, at the start of the
job rollout. This is the initial rate of the rollout.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: Yes
incrementFactor

The rate of increase for a job rollout. The number of things notified is multiplied by this factor.

Type: Double

Required: Yes
rateIncreaseCriteria

The criteria to initiate the increase in rate of rollout for a job.

AWS IoT Core supports up to one digit after the decimal (for example, 1.5, but not 1.55).

Type: AwsJobRateIncreaseCriteria (p. 823) object

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

821
 AWS IoT API Reference
AwsJobPresignedUrlConfig

AwsJobPresignedUrlConfig
Service: AWS IoT

Configuration information for pre-signed URLs. Valid when protocols contains HTTP.

Contents
expiresInSec

How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is
1800 seconds. Pre-signed URLs are generated when a request for the job document is received.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

822
 AWS IoT API Reference
AwsJobRateIncreaseCriteria

AwsJobRateIncreaseCriteria
Service: AWS IoT

The criteria to initiate the increase in rate of rollout for a job.

Contents
numberOfNotifiedThings

When this number of things have been notified, it will initiate an increase in the rollout rate.

Type: Integer

Valid Range: Minimum value of 1.

Required: No
numberOfSucceededThings

When this number of things have succeeded in their job execution, it will initiate an increase in the
rollout rate.

Type: Integer

Valid Range: Minimum value of 1.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

823
 AWS IoT API Reference
AwsJobTimeoutConfig

AwsJobTimeoutConfig
Service: AWS IoT

Specifies the amount of time each device has to finish its execution of the job. A timer is started when
the job execution status is set to IN_PROGRESS. If the job execution status is not set to another terminal
state before the timer expires, it will be automatically set to TIMED_OUT.

Contents
inProgressTimeoutInMinutes

Specifies the amount of time, in minutes, this device has to finish execution of this job. The timeout
interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The in progress timer
can't be updated and will apply to all job executions for the job. Whenever a job execution remains
in the IN_PROGRESS status for longer than this interval, the job execution will fail and switch to the
terminal TIMED_OUT status.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

824
 AWS IoT API Reference
Behavior

Behavior
Service: AWS IoT

A Device Defender security profile behavior.

Contents
criteria

The criteria that determine if a device is behaving normally in regard to the metric.

Type: BehaviorCriteria (p. 827) object

Required: No
metric

What is measured by the behavior.

Type: String

Required: No
metricDimension

The dimension for a metric in your behavior. For example, using a TOPIC_FILTER dimension, you
can narrow down the scope of the metric to only MQTT topics where the name matches the pattern
specified in the dimension. This can't be used with custom metrics.

Type: MetricDimension (p. 915) object

Required: No
name

The name you've given to the behavior.

Type: String

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

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

Required: Yes
suppressAlerts

Suppresses alerts.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2

825
 AWS IoT API Reference
Behavior

• AWS SDK for Ruby V3

826
 AWS IoT API Reference
BehaviorCriteria

BehaviorCriteria
Service: AWS IoT

The criteria by which the behavior is determined to be normal.

Contents
comparisonOperator

The operator that relates the thing measured (metric) to the criteria (containing a value or
statisticalThreshold). Valid operators include:
• string-list: in-set and not-in-set
• number-list: in-set and not-in-set
• ip-address-list: in-cidr-set and not-in-cidr-set
• number: less-than, less-than-equals, greater-than, and greater-than-equals

Type: String

Valid Values: less-than | less-than-equals | greater-than | greater-than-equals

| in-cidr-set | not-in-cidr-set | in-port-set | not-in-port-set | in-set |
not-in-set

Required: No
consecutiveDatapointsToAlarm

If a device is in violation of the behavior for the specified number of consecutive datapoints, an
alarm occurs. If not specified, the default is 1.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 10.

Required: No
consecutiveDatapointsToClear

If an alarm has occurred and the offending device is no longer in violation of the behavior for the
specified number of consecutive datapoints, the alarm is cleared. If not specified, the default is 1.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 10.

Required: No
durationSeconds

Use this to specify the time duration over which the behavior is evaluated, for those criteria that
have a time dimension (for example, NUM_MESSAGES_SENT). For a statisticalThreshhold
metric comparison, measurements from all devices are accumulated over this time duration before
being used to calculate percentiles, and later, measurements from an individual device are also
accumulated over this time duration before being given a percentile rank. Cannot be used with list-
based metric datatypes.

Type: Integer

Required: No
mlDetectionConfig

The configuration of an ML Detect

827
 AWS IoT API Reference
BehaviorCriteria

Type: MachineLearningDetectionConfig (p. 914) object

Required: No
statisticalThreshold

A statistical ranking (percentile)that indicates a threshold value by which a behavior is determined to

be in compliance or in violation of the behavior.

Type: StatisticalThreshold (p. 970) object

Required: No
value

The value to be compared with the metric.

Type: MetricValue (p. 917) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

828
 AWS IoT API Reference
BehaviorModelTrainingSummary

BehaviorModelTrainingSummary
Service: AWS IoT

The summary of an ML Detect behavior model.

Contents
behaviorName

The name of the behavior.

Type: String

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

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

Required: No
datapointsCollectionPercentage

The percentage of datapoints collected.

Type: Double

Valid Range: Minimum value of 0. Maximum value of 100.

Required: No
lastModelRefreshDate

The date the model was last refreshed.

Type: Timestamp

Required: No
modelStatus

The status of the behavior model.

Type: String

Valid Values: PENDING_BUILD | ACTIVE | EXPIRED

Required: No
securityProfileName

The name of the security profile.

Type: String

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

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

Required: No
trainingDataCollectionStartDate

The date a training model started collecting data.

Type: Timestamp

829
 AWS IoT API Reference
BehaviorModelTrainingSummary

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

830
 AWS IoT API Reference
BillingGroupMetadata

BillingGroupMetadata
Service: AWS IoT

Additional information about the billing group.

Contents
creationDate

The date the billing group was created.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

831
 AWS IoT API Reference
BillingGroupProperties

BillingGroupProperties
Service: AWS IoT

The properties of a billing group.

Contents
billingGroupDescription

The description of the billing group.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [\p{Graph}\x20]*

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

832
 AWS IoT API Reference
Bucket

Bucket
Service: AWS IoT

A count of documents that meets a specific aggregation criteria.

Contents
count

The number of documents that have the value counted for the particular bucket.

Type: Integer

Required: No
keyValue

The value counted for the particular bucket.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

833
 AWS IoT API Reference
BucketsAggregationType

BucketsAggregationType
Service: AWS IoT

The type of bucketed aggregation performed.

Contents
termsAggregation

Performs an aggregation that will return a list of buckets. The list of buckets is a ranked list of the
number of occurrences of an aggregation field value.

Type: TermsAggregation (p. 983) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

834
 AWS IoT API Reference
CACertificate

CACertificate
Service: AWS IoT

A CA certificate.

Contents
certificateArn

The ARN of the CA certificate.

Type: String

Required: No
certificateId

The ID of the CA certificate.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
creationDate

The date the CA certificate was created.

Type: Timestamp

Required: No
status

The status of the CA certificate.

The status value REGISTER_INACTIVE is deprecated and should not be used.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

835
 AWS IoT API Reference
CACertificateDescription

CACertificateDescription
Service: AWS IoT

Describes a CA certificate.

Contents
autoRegistrationStatus

Whether the CA certificate configured for auto registration of device certificates. Valid values are
"ENABLE" and "DISABLE"

Type: String

Valid Values: ENABLE | DISABLE

Required: No
certificateArn

The CA certificate ARN.

Type: String

Required: No
certificateId

The CA certificate ID.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
certificatePem

The CA certificate data, in PEM format.

Type: String

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

Required: No
creationDate

The date the CA certificate was created.

Type: Timestamp

Required: No
customerVersion

The customer version of the CA certificate.

Type: Integer

Valid Range: Minimum value of 1.

836
 AWS IoT API Reference
CACertificateDescription

Required: No
generationId

The generation ID of the CA certificate.

Type: String

Required: No
lastModifiedDate

The date the CA certificate was last modified.

Type: Timestamp

Required: No
ownedBy

The owner of the CA certificate.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: No
status

The status of a CA certificate.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
validity

When the CA certificate is valid.

Type: CertificateValidity (p. 843) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

837
 AWS IoT API Reference
Certificate

Certificate
Service: AWS IoT

Information about a certificate.

Contents
certificateArn

The ARN of the certificate.

Type: String

Required: No
certificateId

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
certificateMode

The mode of the certificate.

Type: String

Valid Values: DEFAULT | SNI_ONLY

Required: No
creationDate

The date and time the certificate was created.

Type: Timestamp

Required: No
status

The status of the certificate.

The status value REGISTER_INACTIVE is deprecated and should not be used.

Type: String

Valid Values: ACTIVE | INACTIVE | REVOKED | PENDING_TRANSFER |

REGISTER_INACTIVE | PENDING_ACTIVATION

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

838
 AWS IoT API Reference
Certificate

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

839
 AWS IoT API Reference
CertificateDescription

CertificateDescription
Service: AWS IoT

Describes a certificate.

Contents
caCertificateId

The certificate ID of the CA certificate used to sign this certificate.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
certificateArn

The ARN of the certificate.

Type: String

Required: No
certificateId

The ID of the certificate.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
certificateMode

The mode of the certificate.

Type: String

Valid Values: DEFAULT | SNI_ONLY

Required: No
certificatePem

The certificate data, in PEM format.

Type: String

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

Required: No
creationDate

The date and time the certificate was created.

Type: Timestamp

840
 AWS IoT API Reference
CertificateDescription

Required: No
customerVersion

The customer version of the certificate.

Type: Integer

Valid Range: Minimum value of 1.

Required: No
generationId

The generation ID of the certificate.

Type: String

Required: No
lastModifiedDate

The date and time the certificate was last modified.

Type: Timestamp

Required: No
ownedBy

The ID of the AWS account that owns the certificate.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: No
previousOwnedBy

The ID of the AWS account of the previous owner of the certificate.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: No
status

The status of the certificate.

Type: String

Valid Values: ACTIVE | INACTIVE | REVOKED | PENDING_TRANSFER |

REGISTER_INACTIVE | PENDING_ACTIVATION

Required: No
transferData

The transfer data.

841
 AWS IoT API Reference
CertificateDescription

Type: TransferData (p. 1015) object

Required: No
validity

When the certificate is valid.

Type: CertificateValidity (p. 843) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

842
 AWS IoT API Reference
CertificateValidity

CertificateValidity
Service: AWS IoT

When the certificate is valid.

Contents
notAfter

The certificate is not valid after this date.

Type: Timestamp

Required: No
notBefore

The certificate is not valid before this date.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

843
 AWS IoT API Reference
CloudwatchAlarmAction

CloudwatchAlarmAction
Service: AWS IoT

Describes an action that updates a CloudWatch alarm.

Contents
alarmName

The CloudWatch alarm name.

Type: String

Required: Yes
roleArn

The IAM role that allows access to the CloudWatch alarm.

Type: String

Required: Yes
stateReason

The reason for the alarm change.

Type: String

Required: Yes
stateValue

The value of the alarm state. Acceptable values are: OK, ALARM, INSUFFICIENT_DATA.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

844
 AWS IoT API Reference
CloudwatchLogsAction

CloudwatchLogsAction
Service: AWS IoT

Describes an action that sends data to CloudWatch Logs.

Contents
logGroupName

The CloudWatch log group to which the action sends data.

Type: String

Required: Yes
roleArn

The IAM role that allows access to the CloudWatch log.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

845
 AWS IoT API Reference
CloudwatchMetricAction

CloudwatchMetricAction
Service: AWS IoT

Describes an action that captures a CloudWatch metric.

Contents
metricName

The CloudWatch metric name.

Type: String

Required: Yes
metricNamespace

The CloudWatch metric namespace name.

Type: String

Required: Yes
metricTimestamp

An optional Unix timestamp.

Type: String

Required: No
metricUnit

The metric unit supported by CloudWatch.

Type: String

Required: Yes
metricValue

The CloudWatch metric value.

Type: String

Required: Yes
roleArn

The IAM role that allows access to the CloudWatch metric.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2

846
 AWS IoT API Reference
CloudwatchMetricAction

• AWS SDK for Ruby V3

847
 AWS IoT API Reference
CodeSigning

CodeSigning
Service: AWS IoT

Describes the method to use when code signing a file.

Contents
awsSignerJobId

The ID of the AWSSignerJob which was created to sign the file.

Type: String

Required: No
customCodeSigning

A custom method for code signing a file.

Type: CustomCodeSigning (p. 852) object

Required: No
startSigningJobParameter

Describes the code-signing job.

Type: StartSigningJobParameter (p. 969) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

848
 AWS IoT API Reference
CodeSigningCertificateChain

CodeSigningCertificateChain
Service: AWS IoT

Describes the certificate chain being used when code signing a file.

Contents
certificateName

The name of the certificate.

Type: String

Required: No
inlineDocument

A base64 encoded binary representation of the code signing certificate chain.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

849
 AWS IoT API Reference
CodeSigningSignature

CodeSigningSignature
Service: AWS IoT

Describes the signature for a file.

Contents
inlineDocument

A base64 encoded binary representation of the code signing signature.

Type: Base64-encoded binary data object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

850
 AWS IoT API Reference
Configuration

Configuration
Service: AWS IoT

Configuration.

Contents
Enabled

True to enable the configuration.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

851
 AWS IoT API Reference
CustomCodeSigning

CustomCodeSigning
Service: AWS IoT

Describes a custom method used to code sign a file.

Contents
certificateChain

The certificate chain.

Type: CodeSigningCertificateChain (p. 849) object

Required: No
hashAlgorithm

The hash algorithm used to code sign the file.

Type: String

Required: No
signature

The signature for the file.

Type: CodeSigningSignature (p. 850) object

Required: No
signatureAlgorithm

The signature algorithm used to code sign the file.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

852
 AWS IoT API Reference
Denied

Denied
Service: AWS IoT

Contains information that denied the authorization.

Contents
explicitDeny

Information that explicitly denies the authorization.

Type: ExplicitDeny (p. 869) object

Required: No
implicitDeny

Information that implicitly denies the authorization. When a policy doesn't explicitly deny or allow
an action on a resource it is considered an implicit deny.

Type: ImplicitDeny (p. 884) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

853
 AWS IoT API Reference
Destination

Destination
Service: AWS IoT

Describes the location of the updated firmware.

Contents
s3Destination

Describes the location in S3 of the updated firmware.

Type: S3Destination (p. 956) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

854
 AWS IoT API Reference
DetectMitigationActionExecution

DetectMitigationActionExecution
Service: AWS IoT

Describes which mitigation actions should be executed.

Contents
actionName

The friendly name that uniquely identifies the mitigation action.

Type: String

Length Constraints: Maximum length of 128.

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

Required: No
errorCode

The error code of a mitigation action.

Type: String

Required: No
executionEndDate

The date a mitigation action ended.

Type: Timestamp

Required: No
executionStartDate

The date a mitigation action was started.

Type: Timestamp

Required: No
message

The message of a mitigation action.

Type: String

Length Constraints: Maximum length of 2048.

Required: No
status

The status of a mitigation action.

Type: String

Valid Values: IN_PROGRESS | SUCCESSFUL | FAILED | SKIPPED

Required: No
taskId

The unique identifier of the task.

855
 AWS IoT API Reference
DetectMitigationActionExecution

Type: String

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

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

Required: No
thingName

The name of the thing.

Type: String

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

Required: No
violationId

The unique identifier of the violation.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

856
 AWS IoT API Reference
DetectMitigationActionsTaskStatistics

DetectMitigationActionsTaskStatistics
Service: AWS IoT

The statistics of a mitigation action task.

Contents
actionsExecuted

The actions that were performed.

Type: Long

Required: No
actionsFailed

The actions that failed.

Type: Long

Required: No
actionsSkipped

The actions that were skipped.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

857
 AWS IoT API Reference
DetectMitigationActionsTaskSummary

DetectMitigationActionsTaskSummary
Service: AWS IoT

The summary of the mitigation action tasks.

Contents
actionsDefinition

The definition of the actions.

Type: Array of MitigationAction (p. 919) objects

Required: No
onlyActiveViolationsIncluded

Includes only active violations.

Type: Boolean

Required: No
suppressedAlertsIncluded

Includes suppressed alerts.

Type: Boolean

Required: No
target

Specifies the ML Detect findings to which the mitigation actions are applied.

Type: DetectMitigationActionsTaskTarget (p. 860) object

Required: No
taskEndTime

The date the task ended.

Type: Timestamp

Required: No
taskId

The unique identifier of the task.

Type: String

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

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

Required: No
taskStartTime

The date the task started.

Type: Timestamp

858
 AWS IoT API Reference
DetectMitigationActionsTaskSummary

Required: No
taskStatistics

The statistics of a mitigation action task.

Type: DetectMitigationActionsTaskStatistics (p. 857) object

Required: No
taskStatus

The status of the task.

Type: String

Valid Values: IN_PROGRESS | SUCCESSFUL | FAILED | CANCELED

Required: No
violationEventOccurrenceRange

Specifies the time period of which violation events occurred between.

Type: ViolationEventOccurrenceRange (p. 1022) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

859
 AWS IoT API Reference
DetectMitigationActionsTaskTarget

DetectMitigationActionsTaskTarget
Service: AWS IoT

The target of a mitigation action task.

Contents
behaviorName

The name of the behavior.

Type: String

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

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

Required: No
securityProfileName

The name of the security profile.

Type: String

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

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

Required: No
violationIds

The unique identifiers of the violations.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 25 items.

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

860
 AWS IoT API Reference
DomainConfigurationSummary

DomainConfigurationSummary
Service: AWS IoT

The summary of a domain configuration. A domain configuration specifies custom IoT-specific

information about a domain. A domain configuration can be associated with an AWS-managed domain
(for example, dbc123defghijk.iot.us-west-2.amazonaws.com), a customer managed domain, or a default
endpoint.

• Data
• Jobs
• CredentialProvider

Contents
domainConfigurationArn

The ARN of the domain configuration.

Type: String

Required: No
domainConfigurationName

The name of the domain configuration. This value must be unique to a region.

Type: String

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

Pattern: [\w.:-]+

Required: No
serviceType

The type of service delivered by the endpoint.

Type: String

Valid Values: DATA | CREDENTIAL_PROVIDER | JOBS

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

861
 AWS IoT API Reference
DynamoDBAction

DynamoDBAction
Service: AWS IoT

Describes an action to write to a DynamoDB table.

The tableName, hashKeyField, and rangeKeyField values must match the values used when you
created the table.

The hashKeyValue and rangeKeyvalue fields use a substitution template syntax. These templates
provide data at runtime. The syntax is as follows: ${sql-expression}.

You can specify any valid expression in a WHERE or SELECT clause, including JSON properties,
comparisons, calculations, and functions. For example, the following field uses the third level of the
topic:

"hashKeyValue": "${topic(3)}"

The following field uses the timestamp:

"rangeKeyValue": "${timestamp()}"

Contents
hashKeyField

The hash key name.

Type: String

Required: Yes
hashKeyType

The hash key type. Valid values are "STRING" or "NUMBER"

Type: String

Valid Values: STRING | NUMBER

Required: No
hashKeyValue

The hash key value.

Type: String

Required: Yes
operation

The type of operation to be performed. This follows the substitution template, so it can be
${operation}, but the substitution must result in one of the following: INSERT, UPDATE, or
DELETE.

Type: String

Required: No
payloadField

The action payload. This name can be customized.

862
 AWS IoT API Reference
DynamoDBAction

Type: String

Required: No
rangeKeyField

The range key name.

Type: String

Required: No
rangeKeyType

The range key type. Valid values are "STRING" or "NUMBER"

Type: String

Valid Values: STRING | NUMBER

Required: No
rangeKeyValue

The range key value.

Type: String

Required: No
roleArn

The ARN of the IAM role that grants access to the DynamoDB table.

Type: String

Required: Yes
tableName

The name of the DynamoDB table.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

863
 AWS IoT API Reference
DynamoDBv2Action

DynamoDBv2Action
Service: AWS IoT

Describes an action to write to a DynamoDB table.

This DynamoDB action writes each attribute in the message payload into it's own column in the
DynamoDB table.

Contents
putItem

Specifies the DynamoDB table to which the message data will be written. For example:

{ "dynamoDBv2": { "roleArn": "aws:iam:12341251:my-role" "putItem":

{ "tableName": "my-table" } } }

Each attribute in the message payload will be written to a separate column in the DynamoDB
database.

Type: PutItemInput (p. 945) object

Required: Yes
roleArn

The ARN of the IAM role that grants access to the DynamoDB table.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

864
 AWS IoT API Reference
EffectivePolicy

EffectivePolicy
Service: AWS IoT

The policy that has the effect on the authorization results.

Contents
policyArn

The policy ARN.

Type: String

Required: No
policyDocument

The IAM policy document.

Type: String

Required: No
policyName

The policy name.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

865
 AWS IoT API Reference
ElasticsearchAction

ElasticsearchAction
Service: AWS IoT

Describes an action that writes data to an Amazon OpenSearch Service domain.

Contents
endpoint

The endpoint of your OpenSearch domain.

Type: String

Pattern: https?://.*

Required: Yes
id

The unique identifier for the document you are storing.

Type: String

Required: Yes
index

The index where you want to store your data.

Type: String

Required: Yes
roleArn

The IAM role ARN that has access to OpenSearch.

Type: String

Required: Yes
type

The type of document you are storing.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

866
 AWS IoT API Reference
EnableIoTLoggingParams

EnableIoTLoggingParams
Service: AWS IoT

Parameters used when defining a mitigation action that enable AWS IoT Core logging.

Contents
logLevel

Specifies the type of information to be logged.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: Yes
roleArnForLogging

The Amazon Resource Name (ARN) of the IAM role used for logging.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

867
 AWS IoT API Reference
ErrorInfo

ErrorInfo
Service: AWS IoT

Error information.

Contents
code

The error code.

Type: String

Required: No
message

The error message.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

868
 AWS IoT API Reference
ExplicitDeny

ExplicitDeny
Service: AWS IoT

Information that explicitly denies authorization.

Contents
policies

The policies that denied the authorization.

Type: Array of Policy (p. 934) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

869
 AWS IoT API Reference
ExponentialRolloutRate

ExponentialRolloutRate
Service: AWS IoT

Allows you to create an exponential rate of rollout for a job.

Contents
baseRatePerMinute

The minimum number of things that will be notified of a pending job, per minute at the start of job
rollout. This parameter allows you to define the initial rate of rollout.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: Yes
incrementFactor

The exponential factor to increase the rate of rollout for a job.

AWS IoT Core supports up to one digit after the decimal (for example, 1.5, but not 1.55).

Type: Double

Valid Range: Minimum value of 1. Maximum value of 5.

Required: Yes
rateIncreaseCriteria

The criteria to initiate the increase in rate of rollout for a job.

Type: RateIncreaseCriteria (p. 946) object

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

870
 AWS IoT API Reference
Field

Field
Service: AWS IoT

Describes the name and data type at a field.

Contents
name

The name of the field.

Type: String

Required: No
type

The data type of the field.

Type: String

Valid Values: Number | String | Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

871
 AWS IoT API Reference
FileLocation

FileLocation
Service: AWS IoT

The location of the OTA update.

Contents
s3Location

The location of the updated firmware in S3.

Type: S3Location (p. 957) object

Required: No
stream

The stream that contains the OTA update.

Type: Stream (p. 974) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

872
 AWS IoT API Reference
FirehoseAction

FirehoseAction
Service: AWS IoT

Describes an action that writes data to an Amazon Kinesis Firehose stream.

Contents
batchMode

Whether to deliver the Kinesis Data Firehose stream as a batch by using PutRecordBatch . The
default value is false.

When batchMode is true and the rule's SQL statement evaluates to an Array, each Array element
forms one record in the PutRecordBatch request. The resulting array can't have more than 500
records.

Type: Boolean

Required: No
deliveryStreamName

The delivery stream name.

Type: String

Required: Yes
roleArn

The IAM role that grants access to the Amazon Kinesis Firehose stream.

Type: String

Required: Yes
separator

A character separator that will be used to separate records written to the Firehose stream. Valid
values are: '\n' (newline), '\t' (tab), '\r\n' (Windows newline), ',' (comma).

Type: String

Pattern: ([\n\t])|(\r\n)|(,)

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

873
 AWS IoT API Reference
FleetMetricNameAndArn

FleetMetricNameAndArn
Service: AWS IoT

The name and ARN of a fleet metric.

Contents
metricArn

The fleet metric ARN.

Type: String

Required: No
metricName

The fleet metric name.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

874
 AWS IoT API Reference
GroupNameAndArn

GroupNameAndArn
Service: AWS IoT

The name and ARN of a group.

Contents
groupArn

The group ARN.

Type: String

Required: No
groupName

The group name.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

875
 AWS IoT API Reference
HttpAction

HttpAction
Service: AWS IoT

Send data to an HTTPS endpoint.

Contents
auth

The authentication method to use when sending data to an HTTPS endpoint.

Type: HttpAuthorization (p. 879) object

Required: No
confirmationUrl

The URL to which AWS IoT sends a confirmation message. The value of the confirmation URL
must be a prefix of the endpoint URL. If you do not specify a confirmation URL AWS IoT uses the
endpoint URL as the confirmation URL. If you use substitution templates in the confirmationUrl, you
must create and enable topic rule destinations that match each possible value of the substitution
template before traffic is allowed to your endpoint URL.

Type: String

Length Constraints: Maximum length of 2000.

Required: No
headers

The HTTP headers to send with the message data.

Type: Array of HttpActionHeader (p. 878) objects

Array Members: Minimum number of 0 items. Maximum number of 100 items.

Required: No
url

The endpoint URL. If substitution templates are used in the URL, you must also specify a
confirmationUrl. If this is a new destination, a new TopicRuleDestination is created if
possible.

Type: String

Length Constraints: Maximum length of 2000.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

876
AWS IoT API Reference
HttpAction

877
 AWS IoT API Reference
HttpActionHeader

HttpActionHeader
Service: AWS IoT

The HTTP action header.

Contents
key

The HTTP header key.

Type: String

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

Required: Yes
value

The HTTP header value. Substitution templates are supported.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

878
 AWS IoT API Reference
HttpAuthorization

HttpAuthorization
Service: AWS IoT

The authorization method used to send messages.

Contents
sigv4

Use Sig V4 authorization. For more information, see Signature Version 4 Signing Process.

Type: SigV4Authorization (p. 966) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

879
 AWS IoT API Reference
HttpContext

HttpContext
Service: AWS IoT

Specifies the HTTP context to use for the test authorizer request.

Contents
headers

The header keys and values in an HTTP authorization request.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 8192.

Value Length Constraints: Minimum length of 1. Maximum length of 8192.

Required: No
queryString

The query string keys and values in an HTTP authorization request.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

880
 AWS IoT API Reference
HttpUrlDestinationConfiguration

HttpUrlDestinationConfiguration
Service: AWS IoT

HTTP URL destination configuration used by the topic rule's HTTP action.

Contents
confirmationUrl

The URL AWS IoT uses to confirm ownership of or access to the topic rule destination URL.

Type: String

Length Constraints: Maximum length of 2000.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

881
 AWS IoT API Reference
HttpUrlDestinationProperties

HttpUrlDestinationProperties
Service: AWS IoT

HTTP URL destination properties.

Contents
confirmationUrl

The URL used to confirm the HTTP topic rule destination URL.

Type: String

Length Constraints: Maximum length of 2000.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

882
 AWS IoT API Reference
HttpUrlDestinationSummary

HttpUrlDestinationSummary
Service: AWS IoT

Information about an HTTP URL destination.

Contents
confirmationUrl

The URL used to confirm ownership of or access to the HTTP topic rule destination URL.

Type: String

Length Constraints: Maximum length of 2000.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

883
 AWS IoT API Reference
ImplicitDeny

ImplicitDeny
Service: AWS IoT

Information that implicitly denies authorization. When policy doesn't explicitly deny or allow an action
on a resource it is considered an implicit deny.

Contents
policies

Policies that don't contain a matching allow or deny statement for the specified action on the
specified resource.

Type: Array of Policy (p. 934) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

884
 AWS IoT API Reference
IotAnalyticsAction

IotAnalyticsAction
Service: AWS IoT

Sends message data to an AWS IoT Analytics channel.

Contents
batchMode

Whether to process the action as a batch. The default value is false.

When batchMode is true and the rule SQL statement evaluates to an Array, each Array element
is delivered as a separate message when passed by BatchPutMessage to the AWS IoT Analytics
channel. The resulting array can't have more than 100 messages.

Type: Boolean

Required: No
channelArn

(deprecated) The ARN of the IoT Analytics channel to which message data will be sent.

Type: String

Required: No
channelName

The name of the IoT Analytics channel to which message data will be sent.

Type: String

Required: No
roleArn

The ARN of the role which has a policy that grants IoT Analytics permission to send message data via
IoT Analytics (iotanalytics:BatchPutMessage).

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

885
 AWS IoT API Reference
IotEventsAction

IotEventsAction
Service: AWS IoT

Sends an input to an AWS IoT Events detector.

Contents
batchMode

Whether to process the event actions as a batch. The default value is false.

When batchMode is true, you can't specify a messageId.

When batchMode is true and the rule SQL statement evaluates to an Array, each Array element is
treated as a separate message when it's sent to AWS IoT Events by calling BatchPutMessage . The
resulting array can't have more than 10 messages.

Type: Boolean

Required: No
inputName

The name of the AWS IoT Events input.

Type: String

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

Required: Yes
messageId

The ID of the message. The default messageId is a new UUID value.

When batchMode is true, you can't specify a messageId--a new UUID value will be assigned.

Assign a value to this property to ensure that only one input (message) with a given messageId will
be processed by an AWS IoT Events detector.

Type: String

Length Constraints: Maximum length of 128.

Required: No
roleArn

The ARN of the role that grants AWS IoT permission to send an input to an AWS IoT Events detector.
("Action":"iotevents:BatchPutMessage").

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

886
 AWS IoT API Reference
IotEventsAction

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

887
 AWS IoT API Reference
IotSiteWiseAction

IotSiteWiseAction
Service: AWS IoT

Describes an action to send data from an MQTT message that triggered the rule to AWS IoT SiteWise
asset properties.

Contents
putAssetPropertyValueEntries

A list of asset property value entries.

Type: Array of PutAssetPropertyValueEntry (p. 943) objects

Array Members: Minimum number of 1 item.

Required: Yes
roleArn

The ARN of the role that grants AWS IoT permission to send an asset property value to AWS IoT
SiteWise. ("Action": "iotsitewise:BatchPutAssetPropertyValue"). The trust policy can
restrict access to specific asset hierarchy paths.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

888
 AWS IoT API Reference
Job

Job
Service: AWS IoT

The Job object contains details about a job.

Contents
abortConfig

Configuration for criteria to abort the job.

Type: AbortConfig (p. 782) object

Required: No
comment

If the job was updated, describes the reason for the update.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
completedAt

The time, in seconds since the epoch, when the job was completed.

Type: Timestamp

Required: No
createdAt

The time, in seconds since the epoch, when the job was created.

Type: Timestamp

Required: No
description

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
forceCanceled

Will be true if the job was canceled with the optional force parameter set to true.

Type: Boolean

Required: No
jobArn

An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".

889
 AWS IoT API Reference
Job

Type: String

Required: No
jobExecutionsRolloutConfig

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 895) object

Required: No
jobId

The unique identifier you assigned to this job when it was created.

Type: String

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

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

Required: No
jobProcessDetails

Details about the job process.

Type: JobProcessDetails (p. 901) object

Required: No
jobTemplateArn

The ARN of the job template used to create the job.

Type: String

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

Pattern: ^arn:[!-~]+$

Required: No
lastUpdatedAt

The time, in seconds since the epoch, when the job was last updated.

Type: Timestamp

Required: No
namespaceId

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 notifications 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.

Type: String

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

890
 AWS IoT API Reference
Job

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

Required: No
presignedUrlConfig

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 937) object

Required: No
reasonCode

If the job was updated, provides the reason code for the update.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Upper}\p{Digit}_]+

Required: No
status

The status of the job, one of IN_PROGRESS, CANCELED, DELETION_IN_PROGRESS or COMPLETED.

Type: String

Valid Values: IN_PROGRESS | CANCELED | COMPLETED | DELETION_IN_PROGRESS

Required: No
targets

A list of IoT things and thing groups to which the job should be sent.

Type: Array of strings

Array Members: Minimum number of 1 item.

Length Constraints: Maximum length of 2048.

Required: No
targetSelection

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those
things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be
run on a thing when a change is detected in a target. For example, a job will run on a device when
the thing representing the device is added to a target group, even after the job was completed by all
things originally in the group.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No
timeoutConfig

Specifies the amount of time each device has to finish its execution of the job. A timer is started
when the job execution status is set to IN_PROGRESS. If the job execution status is not set to
another terminal state before the timer expires, it will be automatically set to TIMED_OUT.

891
 AWS IoT API Reference
Job

Type: TimeoutConfig (p. 999) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

892
 AWS IoT API Reference
JobExecution

JobExecution
Service: AWS IoT

The job execution object represents the execution of a job on a particular device.

Contents
approximateSecondsBeforeTimedOut

The estimated number of seconds that remain before the job execution status will be changed
to TIMED_OUT. The timeout interval can be anywhere between 1 minute and 7 days (1 to 10080
minutes). The actual job execution timeout can occur up to 60 seconds later than the estimated
duration. This value will not be included if the job execution has reached a terminal status.

Type: Long

Required: No
executionNumber

A string (consisting of the digits "0" through "9") which identifies this particular job execution on this
particular device. It can be used in commands which return or update job execution information.

Type: Long

Required: No
forceCanceled

Will be true if the job execution was canceled with the optional force parameter set to true.

Type: Boolean

Required: No
jobId

The unique identifier you assigned to the job when it was created.

Type: String

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

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

Required: No
lastUpdatedAt

The time, in seconds since the epoch, when the job execution was last updated.

Type: Timestamp

Required: No
queuedAt

The time, in seconds since the epoch, when the job execution was queued.

Type: Timestamp

Required: No

893
 AWS IoT API Reference
JobExecution

startedAt

The time, in seconds since the epoch, when the job execution started.

Type: Timestamp

Required: No
status

The status of the job execution (IN_PROGRESS, QUEUED, FAILED, SUCCEEDED, TIMED_OUT,
CANCELED, or REJECTED).

Type: String

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED

Required: No
statusDetails

A collection of name/value pairs that describe the status of the job execution.

Type: JobExecutionStatusDetails (p. 896) object

Required: No
thingArn

The ARN of the thing on which the job execution is running.

Type: String

Required: No
versionNumber

The version of the job execution. Job execution versions are incremented each time they are updated
by a device.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

894
 AWS IoT API Reference
JobExecutionsRolloutConfig

JobExecutionsRolloutConfig
Service: AWS IoT

Allows you to create a staged rollout of a job.

Contents
exponentialRate

The rate of increase for a job rollout. This parameter allows you to define an exponential rate for a
job rollout.

Type: ExponentialRolloutRate (p. 870) object

Required: No
maximumPerMinute

The maximum number of things that will be notified of a pending job, per minute. This parameter
allows you to create a staged rollout.

Type: Integer

Valid Range: Minimum value of 1.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

895
 AWS IoT API Reference
JobExecutionStatusDetails

JobExecutionStatusDetails
Service: AWS IoT

Details of the job execution status.

Contents
detailsMap

The job execution status.

Type: String to string map

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

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

Value Length Constraints: Minimum length of 1.

Value Pattern: [^\p{C}]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

896
 AWS IoT API Reference
JobExecutionSummary

JobExecutionSummary
Service: AWS IoT

The job execution summary.

Contents
executionNumber

A string (consisting of the digits "0" through "9") which identifies this particular job execution
on this particular device. It can be used later in commands which return or update job execution
information.

Type: Long

Required: No
lastUpdatedAt

The time, in seconds since the epoch, when the job execution was last updated.

Type: Timestamp

Required: No
queuedAt

The time, in seconds since the epoch, when the job execution was queued.

Type: Timestamp

Required: No
startedAt

The time, in seconds since the epoch, when the job execution started.

Type: Timestamp

Required: No
status

The status of the job execution.

Type: String

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

897
AWS IoT API Reference
JobExecutionSummary

898
 AWS IoT API Reference
JobExecutionSummaryForJob

JobExecutionSummaryForJob
Service: AWS IoT

Contains a summary of information about job executions for a specific job.

Contents
jobExecutionSummary

Contains a subset of information about a job execution.

Type: JobExecutionSummary (p. 897) object

Required: No
thingArn

The ARN of the thing on which the job execution is running.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

899
 AWS IoT API Reference
JobExecutionSummaryForThing

JobExecutionSummaryForThing
Service: AWS IoT

The job execution summary for a thing.

Contents
jobExecutionSummary

Contains a subset of information about a job execution.

Type: JobExecutionSummary (p. 897) object

Required: No
jobId

The unique identifier you assigned to this job when it was created.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

900
 AWS IoT API Reference
JobProcessDetails

JobProcessDetails
Service: AWS IoT

The job process details.

Contents
numberOfCanceledThings

The number of things that cancelled the job.

Type: Integer

Required: No
numberOfFailedThings

The number of things that failed executing the job.

Type: Integer

Required: No
numberOfInProgressThings

The number of things currently executing the job.

Type: Integer

Required: No
numberOfQueuedThings

The number of things that are awaiting execution of the job.

Type: Integer

Required: No
numberOfRejectedThings

The number of things that rejected the job.

Type: Integer

Required: No
numberOfRemovedThings

The number of things that are no longer scheduled to execute the job because they have been
deleted or have been removed from the group that was a target of the job.

Type: Integer

Required: No
numberOfSucceededThings

The number of things which successfully completed the job.

Type: Integer

Required: No

901
 AWS IoT API Reference
JobProcessDetails

numberOfTimedOutThings

The number of things whose job execution status is TIMED_OUT.

Type: Integer

Required: No
processingTargets

The target devices to which the job execution is being rolled out. This value will be null after the job
execution has finished rolling out to all the target devices.

Type: Array of strings

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

902
 AWS IoT API Reference
JobSummary

JobSummary
Service: AWS IoT

The job summary.

Contents
completedAt

The time, in seconds since the epoch, when the job completed.

Type: Timestamp

Required: No
createdAt

The time, in seconds since the epoch, when the job was created.

Type: Timestamp

Required: No
jobArn

The job ARN.

Type: String

Required: No
jobId

The unique identifier you assigned to this job when it was created.

Type: String

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

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

Required: No
lastUpdatedAt

The time, in seconds since the epoch, when the job was last updated.

Type: Timestamp

Required: No
status

The job summary status.

Type: String

Valid Values: IN_PROGRESS | CANCELED | COMPLETED | DELETION_IN_PROGRESS

Required: No
targetSelection

Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those
things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be

903
 AWS IoT API Reference
JobSummary

run on a thing when a change is detected in a target. For example, a job will run on a thing when
the thing is added to a target group, even after the job was completed by all things originally in the
group.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No
thingGroupId

The ID of the thing group.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

904
 AWS IoT API Reference
JobTemplateSummary

JobTemplateSummary
Service: AWS IoT

An object that contains information about the job template.

Contents
createdAt

The time, in seconds since the epoch, when the job template was created.

Type: Timestamp

Required: No
description

A description of the job template.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
jobTemplateArn

The ARN of the job template.

Type: String

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

Pattern: ^arn:[!-~]+$

Required: No
jobTemplateId

The unique identifier of the job template.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

905
AWS IoT API Reference
JobTemplateSummary

906
 AWS IoT API Reference
KafkaAction

KafkaAction
Service: AWS IoT

Send messages to an Amazon Managed Streaming for Apache Kafka (Amazon MSK) or self-managed
Apache Kafka cluster.

Contents
clientProperties

Properties of the Apache Kafka producer client.

Type: String to string map

Required: Yes
destinationArn

The ARN of Kafka action's VPC TopicRuleDestination.

Type: String

Required: Yes
key

The Kafka message key.

Type: String

Required: No
partition

The Kafka message partition.

Type: String

Required: No
topic

The Kafka topic for messages to be sent to the Kafka broker.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

907
 AWS IoT API Reference
KeyPair

KeyPair
Service: AWS IoT

Describes a key pair.

Contents
PrivateKey

The private key.

Type: String

Length Constraints: Minimum length of 1.

Required: No
PublicKey

The public key.

Type: String

Length Constraints: Minimum length of 1.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

908
 AWS IoT API Reference
KinesisAction

KinesisAction
Service: AWS IoT

Describes an action to write data to an Amazon Kinesis stream.

Contents
partitionKey

The partition key.

Type: String

Required: No
roleArn

The ARN of the IAM role that grants access to the Amazon Kinesis stream.

Type: String

Required: Yes
streamName

The name of the Amazon Kinesis stream.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

909
 AWS IoT API Reference
LambdaAction

LambdaAction
Service: AWS IoT

Describes an action to invoke a Lambda function.

Contents
functionArn

The ARN of the Lambda function.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

910
 AWS IoT API Reference
LoggingOptionsPayload

LoggingOptionsPayload
Service: AWS IoT

Describes the logging options payload.

Contents
logLevel

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

911
 AWS IoT API Reference
LogTarget

LogTarget
Service: AWS IoT

A log target.

Contents
targetName

The target name.

Type: String

Required: No
targetType

The target type.

Type: String

Valid Values: DEFAULT | THING_GROUP

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

912
 AWS IoT API Reference
LogTargetConfiguration

LogTargetConfiguration
Service: AWS IoT

The target configuration.

Contents
logLevel

The logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
logTarget

A log target

Type: LogTarget (p. 912) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

913
 AWS IoT API Reference
MachineLearningDetectionConfig

MachineLearningDetectionConfig
Service: AWS IoT

The configuration of an ML Detect Security Profile.

Contents
confidenceLevel

The sensitivity of anomalous behavior evaluation. Can be Low, Medium, or High.

Type: String

Valid Values: LOW | MEDIUM | HIGH

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

914
 AWS IoT API Reference
MetricDimension

MetricDimension
Service: AWS IoT

The dimension of a metric.

Contents
dimensionName

A unique identifier for the dimension.

Type: String

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

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

Required: Yes
operator

Defines how the dimensionValues of a dimension are interpreted. For example, for dimension
type TOPIC_FILTER, the IN operator, a message will be counted only if its topic matches one of the
topic filters. With NOT_IN operator, a message will be counted only if it doesn't match any of the
topic filters. The operator is optional: if it's not provided (is null), it will be interpreted as IN.

Type: String

Valid Values: IN | NOT_IN

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

915
 AWS IoT API Reference
MetricToRetain

MetricToRetain
Service: AWS IoT

The metric you want to retain. Dimensions are optional.

Contents
metric

What is measured by the behavior.

Type: String

Required: Yes
metricDimension

The dimension of a metric. This can't be used with custom metrics.

Type: MetricDimension (p. 915) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

916
 AWS IoT API Reference
MetricValue

MetricValue
Service: AWS IoT

The value to be compared with the metric.

Contents
cidrs

If the comparisonOperator calls for a set of CIDRs, use this to specify that set to be compared
with the metric.

Type: Array of strings

Length Constraints: Minimum length of 2. Maximum length of 43.

Pattern: [a-fA-F0-9:\.\/]+

Required: No
count

If the comparisonOperator calls for a numeric value, use this to specify that numeric value to be
compared with the metric.

Type: Long

Valid Range: Minimum value of 0.

Required: No
number

The numeral value of a metric.

Type: Double

Required: No
numbers

The numeral values of a metric.

Type: Array of doubles

Required: No
ports

If the comparisonOperator calls for a set of ports, use this to specify that set to be compared with
the metric.

Type: Array of integers

Valid Range: Minimum value of 0. Maximum value of 65535.

Required: No
strings

The string values of a metric.

Type: Array of strings

917
 AWS IoT API Reference
MetricValue

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

918
 AWS IoT API Reference
MitigationAction

MitigationAction
Service: AWS IoT

Describes which changes should be applied as part of a mitigation action.

Contents
actionParams

The set of parameters for this mitigation action. The parameters vary, depending on the kind of
action you apply.

Type: MitigationActionParams (p. 921) object

Required: No
id

A unique identifier for the mitigation action.

Type: String

Required: No
name

A user-friendly name for the mitigation action.

Type: String

Length Constraints: Maximum length of 128.

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

Required: No
roleArn

The IAM role ARN used to apply this mitigation action.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

919
 AWS IoT API Reference
MitigationActionIdentifier

MitigationActionIdentifier
Service: AWS IoT

Information that identifies a mitigation action. This information is returned by ListMitigationActions.

Contents
actionArn

The IAM role ARN used to apply this mitigation action.

Type: String

Required: No
actionName

The friendly name of the mitigation action.

Type: String

Length Constraints: Maximum length of 128.

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

Required: No
creationDate

The date when this mitigation action was created.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

920
 AWS IoT API Reference
MitigationActionParams

MitigationActionParams
Service: AWS IoT

The set of parameters for this mitigation action. You can specify only one type of parameter (in other
words, you can apply only one action for each defined mitigation action).

Contents
addThingsToThingGroupParams

Parameters to define a mitigation action that moves devices associated with a certificate to one or
more specified thing groups, typically for quarantine.

Type: AddThingsToThingGroupParams (p. 790) object

Required: No
enableIoTLoggingParams

Parameters to define a mitigation action that enables AWS IoT Core logging at a specified level of
detail.

Type: EnableIoTLoggingParams (p. 867) object

Required: No
publishFindingToSnsParams

Parameters to define a mitigation action that publishes findings to Amazon Simple Notification
Service (Amazon SNS. You can implement your own custom actions in response to the Amazon SNS
messages.

Type: PublishFindingToSnsParams (p. 942) object

Required: No
replaceDefaultPolicyVersionParams

Parameters to define a mitigation action that adds a blank policy to restrict permissions.

Type: ReplaceDefaultPolicyVersionParams (p. 949) object

Required: No
updateCACertificateParams

Parameters to define a mitigation action that changes the state of the CA certificate to inactive.

Type: UpdateCACertificateParams (p. 1016) object

Required: No
updateDeviceCertificateParams

Parameters to define a mitigation action that changes the state of the device certificate to inactive.

Type: UpdateDeviceCertificateParams (p. 1017) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

921
 AWS IoT API Reference
MitigationActionParams

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

922
 AWS IoT API Reference
MqttContext

MqttContext
Service: AWS IoT

Specifies the MQTT context to use for the test authorizer request

Contents
clientId

The value of the clientId key in an MQTT authorization request.

Type: String

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

Required: No
password

The value of the password key in an MQTT authorization request.

Type: Base64-encoded binary data object

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

Required: No
username

The value of the username key in an MQTT authorization request.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

923
 AWS IoT API Reference
NonCompliantResource

NonCompliantResource
Service: AWS IoT

Information about the resource that was noncompliant with the audit check.

Contents
additionalInfo

Other information about the noncompliant resource.

Type: String to string map

Required: No
resourceIdentifier

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 951) object

Required: No
resourceType

The type of the noncompliant resource.

Type: String

Valid Values: DEVICE_CERTIFICATE | CA_CERTIFICATE | IOT_POLICY |

COGNITO_IDENTITY_POOL | CLIENT_ID | ACCOUNT_SETTINGS | ROLE_ALIAS | IAM_ROLE

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

924
 AWS IoT API Reference
OTAUpdateFile

OTAUpdateFile
Service: AWS IoT

Describes a file to be associated with an OTA update.

Contents
attributes

A list of name/attribute pairs.

Type: String to string map

Required: No
codeSigning

The code signing method of the file.

Type: CodeSigning (p. 848) object

Required: No
fileLocation

The location of the updated firmware.

Type: FileLocation (p. 872) object

Required: No
fileName

The name of the file.

Type: String

Required: No
fileType

An integer value you can include in the job document to allow your devices to identify the type of
file received from the cloud.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 255.

Required: No
fileVersion

The file version.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

925
 AWS IoT API Reference
OTAUpdateFile

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

926
 AWS IoT API Reference
OTAUpdateInfo

OTAUpdateInfo
Service: AWS IoT

Information about an OTA update.

Contents
additionalParameters

A collection of name/value pairs

Type: String to string map

Required: No
awsIotJobArn

The AWS IoT job ARN associated with the OTA update.

Type: String

Required: No
awsIotJobId

The AWS IoT job ID associated with the OTA update.

Type: String

Required: No
awsJobExecutionsRolloutConfig

Configuration for the rollout of OTA updates.

Type: AwsJobExecutionsRolloutConfig (p. 820) object

Required: No
awsJobPresignedUrlConfig

Configuration information for pre-signed URLs. Valid when protocols contains HTTP.

Type: AwsJobPresignedUrlConfig (p. 822) object

Required: No
creationDate

The date when the OTA update was created.

Type: Timestamp

Required: No
description

A description of the OTA update.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

927
 AWS IoT API Reference
OTAUpdateInfo

Required: No
errorInfo

Error information associated with the OTA update.

Type: ErrorInfo (p. 868) object

Required: No
lastModifiedDate

The date when the OTA update was last updated.

Type: Timestamp

Required: No
otaUpdateArn

The OTA update ARN.

Type: String

Required: No
otaUpdateFiles

A list of files associated with the OTA update.

Type: Array of OTAUpdateFile (p. 925) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: No
otaUpdateId

The OTA update ID.

Type: String

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

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

Required: No
otaUpdateStatus

The status of the OTA update.

Type: String

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED

Required: No
protocols

The protocol used to transfer the OTA update image. Valid values are [HTTP], [MQTT], [HTTP,
MQTT]. When both HTTP and MQTT are specified, the target device can choose the protocol.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 2 items.

928
 AWS IoT API Reference
OTAUpdateInfo

Valid Values: MQTT | HTTP

Required: No
targets

The targets of the OTA update.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: No
targetSelection

Specifies whether the OTA update will continue to run (CONTINUOUS), or will be complete after all
those things specified as targets have completed the OTA update (SNAPSHOT). If continuous, the
OTA update may also be run on a thing when a change is detected in a target. For example, an OTA
update will run on a thing when the thing is added to a target group, even after the OTA update was
completed by all things originally in the group.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

929
 AWS IoT API Reference
OTAUpdateSummary

OTAUpdateSummary
Service: AWS IoT

An OTA update summary.

Contents
creationDate

The date when the OTA update was created.

Type: Timestamp

Required: No
otaUpdateArn

The OTA update ARN.

Type: String

Required: No
otaUpdateId

The OTA update ID.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

930
 AWS IoT API Reference
OutgoingCertificate

OutgoingCertificate
Service: AWS IoT

A certificate that has been transferred but not yet accepted.

Contents
certificateArn

The certificate ARN.

Type: String

Required: No
certificateId

The certificate ID.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
creationDate

The certificate creation date.

Type: Timestamp

Required: No
transferDate

The date the transfer was initiated.

Type: Timestamp

Required: No
transferMessage

The transfer message.

Type: String

Length Constraints: Maximum length of 128.

Required: No
transferredTo

The AWS account to which the transfer was made.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: No

931
 AWS IoT API Reference
OutgoingCertificate

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

932
 AWS IoT API Reference
PercentPair

PercentPair
Service: AWS IoT

Describes the percentile and percentile value.

Contents
percent

The percentile.

Type: Double

Valid Range: Minimum value of 0. Maximum value of 100.

Required: No
value

The value of the percentile.

Type: Double

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

933
 AWS IoT API Reference
Policy

Policy
Service: AWS IoT

Describes an AWS IoT policy.

Contents
policyArn

The policy ARN.

Type: String

Required: No
policyName

The policy name.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

934
 AWS IoT API Reference
PolicyVersion

PolicyVersion
Service: AWS IoT

Describes a policy version.

Contents
createDate

The date and time the policy was created.

Type: Timestamp

Required: No
isDefaultVersion

Specifies whether the policy version is the default.

Type: Boolean

Required: No
versionId

The policy version ID.

Type: String

Pattern: [0-9]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

935
 AWS IoT API Reference
PolicyVersionIdentifier

PolicyVersionIdentifier
Service: AWS IoT

Information about the version of the policy associated with the resource.

Contents
policyName

The name of the policy.

Type: String

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

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

Required: No
policyVersionId

The ID of the version of the policy associated with the resource.

Type: String

Pattern: [0-9]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

936
 AWS IoT API Reference
PresignedUrlConfig

PresignedUrlConfig
Service: AWS IoT

Configuration for pre-signed S3 URLs.

Contents
expiresInSec

How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is
3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job
document.

Type: Long

Valid Range: Minimum value of 60. Maximum value of 3600.

Required: No
roleArn

The ARN of an IAM role that grants grants permission to download files from the S3 bucket where
the job data/updates are stored. The role must also grant permission for IoT to download the files.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

937
 AWS IoT API Reference
ProvisioningHook

ProvisioningHook
Service: AWS IoT

Structure that contains payloadVersion and targetArn.

Contents
payloadVersion

The payload that was sent to the target function.

Note: Only Lambda functions are currently supported.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 32.

Pattern: ^[0-9-]+$

Required: No
targetArn

The ARN of the target function.

Note: Only Lambda functions are currently supported.

Type: String

Length Constraints: Maximum length of 2048.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

938
 AWS IoT API Reference
ProvisioningTemplateSummary

ProvisioningTemplateSummary
Service: AWS IoT

A summary of information about a fleet provisioning template.

Contents
creationDate

The date when the fleet provisioning template summary was created.

Type: Timestamp

Required: No
description

The description of the fleet provisioning template.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: [^\p{C}]*

Required: No
enabled

True if the fleet provision template is enabled, otherwise false.

Type: Boolean

Required: No
lastModifiedDate

The date when the fleet provisioning template summary was last modified.

Type: Timestamp

Required: No
templateArn

The ARN of the fleet provisioning template.

Type: String

Required: No
templateName

The name of the fleet provisioning template.

Type: String

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

Pattern: ^[0-9A-Za-z_-]+$

Required: No

939
 AWS IoT API Reference
ProvisioningTemplateSummary

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

940
 AWS IoT API Reference
ProvisioningTemplateVersionSummary

ProvisioningTemplateVersionSummary
Service: AWS IoT

A summary of information about a fleet provision template version.

Contents
creationDate

The date when the fleet provisioning template version was created

Type: Timestamp

Required: No
isDefaultVersion

True if the fleet provisioning template version is the default version, otherwise false.

Type: Boolean

Required: No
versionId

The ID of the fleet privisioning template version.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

941
 AWS IoT API Reference
PublishFindingToSnsParams

PublishFindingToSnsParams
Service: AWS IoT

Parameters to define a mitigation action that publishes findings to Amazon SNS. You can implement
your own custom actions in response to the Amazon SNS messages.

Contents
topicArn

The ARN of the topic to which you want to publish the findings.

Type: String

Length Constraints: Maximum length of 350.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

942
 AWS IoT API Reference
PutAssetPropertyValueEntry

PutAssetPropertyValueEntry
Service: AWS IoT

An asset property value entry containing the following information.

Contents
assetId

The ID of the AWS IoT SiteWise asset. You must specify either a propertyAlias or both an
aliasId and a propertyId. Accepts substitution templates.

Type: String

Required: No
entryId

Optional. A unique identifier for this entry that you can define to better track which message caused
an error in case of failure. Accepts substitution templates. Defaults to a new UUID.

Type: String

Required: No
propertyAlias

The name of the property alias associated with your asset property. You must specify either a
propertyAlias or both an aliasId and a propertyId. Accepts substitution templates.

Type: String

Length Constraints: Minimum length of 1.

Required: No
propertyId

The ID of the asset's property. You must specify either a propertyAlias or both an aliasId and a
propertyId. Accepts substitution templates.

Type: String

Required: No
propertyValues

A list of property values to insert that each contain timestamp, quality, and value (TQV) information.

Type: Array of AssetPropertyValue (p. 795) objects

Array Members: Minimum number of 1 item.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go

943
 AWS IoT API Reference
PutAssetPropertyValueEntry

• AWS SDK for Java V2

• AWS SDK for Ruby V3

944
 AWS IoT API Reference
PutItemInput

PutItemInput
Service: AWS IoT

The input for the DynamoActionVS action that specifies the DynamoDB table to which the message data
will be written.

Contents
tableName

The table where the message data will be written.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

945
 AWS IoT API Reference
RateIncreaseCriteria

RateIncreaseCriteria
Service: AWS IoT

Allows you to define a criteria to initiate the increase in rate of rollout for a job.

Contents
numberOfNotifiedThings

The threshold for number of notified things that will initiate the increase in rate of rollout.

Type: Integer

Valid Range: Minimum value of 1.

Required: No
numberOfSucceededThings

The threshold for number of succeeded things that will initiate the increase in rate of rollout.

Type: Integer

Valid Range: Minimum value of 1.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

946
 AWS IoT API Reference
RegistrationConfig

RegistrationConfig
Service: AWS IoT

The registration configuration.

Contents
roleArn

The ARN of the role.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
templateBody

The template body.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

947
 AWS IoT API Reference
RelatedResource

RelatedResource
Service: AWS IoT

Information about a related resource.

Contents
additionalInfo

Other information about the resource.

Type: String to string map

Required: No
resourceIdentifier

Information that identifies the resource.

Type: ResourceIdentifier (p. 951) object

Required: No
resourceType

The type of resource.

Type: String

Valid Values: DEVICE_CERTIFICATE | CA_CERTIFICATE | IOT_POLICY |

COGNITO_IDENTITY_POOL | CLIENT_ID | ACCOUNT_SETTINGS | ROLE_ALIAS | IAM_ROLE

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

948
 AWS IoT API Reference
ReplaceDefaultPolicyVersionParams

ReplaceDefaultPolicyVersionParams
Service: AWS IoT

Parameters to define a mitigation action that adds a blank policy to restrict permissions.

Contents
templateName

The name of the template to be applied. The only supported value is BLANK_POLICY.

Type: String

Valid Values: BLANK_POLICY

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

949
 AWS IoT API Reference
RepublishAction

RepublishAction
Service: AWS IoT

Describes an action to republish to another topic.

Contents
qos

The Quality of Service (QoS) level to use when republishing messages. The default value is 0.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 1.

Required: No
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes
topic

The name of the MQTT topic.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

950
 AWS IoT API Reference
ResourceIdentifier

ResourceIdentifier
Service: AWS IoT

Information that identifies the noncompliant resource.

Contents
account

The account with which the resource is associated.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: No
caCertificateId

The ID of the CA certificate used to authorize the certificate.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
clientId

The client ID.

Type: String

Required: No
cognitoIdentityPoolId

The ID of the Amazon Cognito identity pool.

Type: String

Required: No
deviceCertificateId

The ID of the certificate attached to the resource.

Type: String

Length Constraints: Fixed length of 64.

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

Required: No
iamRoleArn

The ARN of the IAM role that has overly permissive actions.

Type: String

951
 AWS IoT API Reference
ResourceIdentifier

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
policyVersionIdentifier

The version of the policy associated with the resource.

Type: PolicyVersionIdentifier (p. 936) object

Required: No
roleAliasArn

The ARN of the role alias that has overly permissive actions.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

952
 AWS IoT API Reference
RoleAliasDescription

RoleAliasDescription
Service: AWS IoT

Role alias description.

Contents
creationDate

The UNIX timestamp of when the role alias was created.

Type: Timestamp

Required: No
credentialDurationSeconds

The number of seconds for which the credential is valid.

Type: Integer

Valid Range: Minimum value of 900. Maximum value of 43200.

Required: No
lastModifiedDate

The UNIX timestamp of when the role alias was last modified.

Type: Timestamp

Required: No
owner

The role alias owner.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

Required: No
roleAlias

The role alias.

Type: String

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

Pattern: [\w=,@-]+

Required: No
roleAliasArn

The ARN of the role alias.

Type: String

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

953
 AWS IoT API Reference
RoleAliasDescription

Required: No
roleArn

The role ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

954
 AWS IoT API Reference
S3Action

S3Action
Service: AWS IoT

Describes an action to write data to an Amazon S3 bucket.

Contents
bucketName

The Amazon S3 bucket.

Type: String

Required: Yes
cannedAcl

The Amazon S3 canned ACL that controls access to the object identified by the object key. For more
information, see S3 canned ACLs.

Type: String

Valid Values: private | public-read | public-read-write | aws-exec-read |

authenticated-read | bucket-owner-read | bucket-owner-full-control | log-
delivery-write

Required: No
key

The object key. For more information, see Actions, resources, and condition keys for Amazon S3.

Type: String

Required: Yes
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

955
 AWS IoT API Reference
S3Destination

S3Destination
Service: AWS IoT

Describes the location of updated firmware in S3.

Contents
bucket

The S3 bucket that contains the updated firmware.

Type: String

Length Constraints: Minimum length of 1.

Required: No
prefix

The S3 prefix.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

956
 AWS IoT API Reference
S3Location

S3Location
Service: AWS IoT

The S3 location.

Contents
bucket

The S3 bucket.

Type: String

Length Constraints: Minimum length of 1.

Required: No
key

The S3 key.

Type: String

Length Constraints: Minimum length of 1.

Required: No
version

The S3 bucket version.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

957
 AWS IoT API Reference
SalesforceAction

SalesforceAction
Service: AWS IoT

Describes an action to write a message to a Salesforce IoT Cloud Input Stream.

Contents
token

The token used to authenticate access to the Salesforce IoT Cloud Input Stream. The token is
available from the Salesforce IoT Cloud platform after creation of the Input Stream.

Type: String

Length Constraints: Minimum length of 40.

Required: Yes
url

The URL exposed by the Salesforce IoT Cloud Input Stream. The URL is available from the Salesforce
IoT Cloud platform after creation of the Input Stream.

Type: String

Length Constraints: Maximum length of 2000.

Pattern: https://ingestion-[a-zA-Z0-9]{1,12}\.[a-zA-Z0-9]+\.((sfdc-matrix
\.net)|(sfdcnow\.com))/streams/\w{1,20}/\w{1,20}/event

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

958
 AWS IoT API Reference
ScheduledAuditMetadata

ScheduledAuditMetadata
Service: AWS IoT

Information about the scheduled audit.

Contents
dayOfMonth

The day of the month on which the scheduled audit is run (if the frequency is "MONTHLY"). If
days 29-31 are specified, and the month does not have that many days, the audit takes place on the
"LAST" day of the month.

Type: String

Pattern: ^([1-9]|[12][0-9]|3[01])$|^LAST$

Required: No
dayOfWeek

The day of the week on which the scheduled audit is run (if the frequency is "WEEKLY" or
"BIWEEKLY").

Type: String

Valid Values: SUN | MON | TUE | WED | THU | FRI | SAT

Required: No
frequency

How often the scheduled audit occurs.

Type: String

Valid Values: DAILY | WEEKLY | BIWEEKLY | MONTHLY

Required: No
scheduledAuditArn

The ARN of the scheduled audit.

Type: String

Required: No
scheduledAuditName

The name of the scheduled audit.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

959
 AWS IoT API Reference
ScheduledAuditMetadata

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

960
 AWS IoT API Reference
SecurityProfileIdentifier

SecurityProfileIdentifier
Service: AWS IoT

Identifying information for a Device Defender security profile.

Contents
arn

The ARN of the security profile.

Type: String

Required: Yes
name

The name you've given to the security profile.

Type: String

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

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

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

961
 AWS IoT API Reference
SecurityProfileTarget

SecurityProfileTarget
Service: AWS IoT

A target to which an alert is sent when a security profile behavior is violated.

Contents
arn

The ARN of the security profile.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

962
 AWS IoT API Reference
SecurityProfileTargetMapping

SecurityProfileTargetMapping
Service: AWS IoT

Information about a security profile and the target associated with it.

Contents
securityProfileIdentifier

Information that identifies the security profile.

Type: SecurityProfileIdentifier (p. 961) object

Required: No
target

Information about the target (thing group) associated with the security profile.

Type: SecurityProfileTarget (p. 962) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

963
 AWS IoT API Reference
ServerCertificateSummary

ServerCertificateSummary
Service: AWS IoT

An object that contains information about a server certificate.

Contents
serverCertificateArn

The ARN of the server certificate.

Type: String

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

Pattern: arn:aws(-cn|-us-gov|-iso-b|-iso)?:acm:[a-z]{2}-(gov-|iso-|isob-)?[a-
z]{4,9}-\d{1}:\d{12}:certificate/[a-zA-Z0-9/-]+

Required: No
serverCertificateStatus

The status of the server certificate.

Type: String

Valid Values: INVALID | VALID

Required: No
serverCertificateStatusDetail

Details that explain the status of the server certificate.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

964
 AWS IoT API Reference
SigningProfileParameter

SigningProfileParameter
Service: AWS IoT

Describes the code-signing profile.

Contents
certificateArn

Certificate ARN.

Type: String

Required: No
certificatePathOnDevice

The location of the code-signing certificate on your device.

Type: String

Required: No
platform

The hardware platform of your device.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

965
 AWS IoT API Reference
SigV4Authorization

SigV4Authorization
Service: AWS IoT

For more information, see Signature Version 4 signing process.

Contents
roleArn

The ARN of the signing role.

Type: String

Required: Yes
serviceName

The service name to use while signing with Sig V4.

Type: String

Required: Yes
signingRegion

The signing region.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

966
 AWS IoT API Reference
SnsAction

SnsAction
Service: AWS IoT

Describes an action to publish to an Amazon SNS topic.

Contents
messageFormat

(Optional) The message format of the message to publish. Accepted values are "JSON" and "RAW".
The default value of the attribute is "RAW". SNS uses this setting to determine if the payload should
be parsed and relevant platform-specific bits of the payload should be extracted. To read more
about SNS message formats, see https://docs.aws.amazon.com/sns/latest/dg/json-formats.html
refer to their official documentation.

Type: String

Valid Values: RAW | JSON

Required: No
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes
targetArn

The ARN of the SNS topic.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

967
 AWS IoT API Reference
SqsAction

SqsAction
Service: AWS IoT

Describes an action to publish data to an Amazon SQS queue.

Contents
queueUrl

The URL of the Amazon SQS queue.

Type: String

Required: Yes
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes
useBase64

Specifies whether to use Base64 encoding.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

968
 AWS IoT API Reference
StartSigningJobParameter

StartSigningJobParameter
Service: AWS IoT

Information required to start a signing job.

Contents
destination

The location to write the code-signed file.

Type: Destination (p. 854) object

Required: No
signingProfileName

The code-signing profile name.

Type: String

Required: No
signingProfileParameter

Describes the code-signing profile.

Type: SigningProfileParameter (p. 965) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

969
 AWS IoT API Reference
StatisticalThreshold

StatisticalThreshold
Service: AWS IoT

A statistical ranking (percentile) that indicates a threshold value by which a behavior is determined to be
in compliance or in violation of the behavior.

Contents
statistic

The percentile that resolves to a threshold value by which compliance with a behavior is determined.
Metrics are collected over the specified period (durationSeconds) from all reporting devices
in your account and statistical ranks are calculated. Then, the measurements from a device are
collected over the same period. If the accumulated measurements from the device fall above or
below (comparisonOperator) the value associated with the percentile specified, then the device is
considered to be in compliance with the behavior, otherwise a violation occurs.

Type: String

Pattern: (p0|p0\.1|p0\.01|p1|p10|p50|p90|p99|p99\.9|p99\.99|p100)

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

970
 AWS IoT API Reference
Statistics

Statistics
Service: AWS IoT

A map of key-value pairs for all supported statistics. Currently, only count is supported.

Contents
average

The average of the aggregated field values.

Type: Double

Required: No
count

The count of things that match the query.

Type: Integer

Required: No
maximum

The maximum aggregated field value.

Type: Double

Required: No
minimum

The minimum aggregated field value.

Type: Double

Required: No
stdDeviation

The standard deviation of the aggregated field values.

Type: Double

Required: No
sum

The sum of the aggregated field values.

Type: Double

Required: No
sumOfSquares

The sum of the squares of the aggregated field values.

Type: Double

Required: No
variance

The variance of the aggregated field values.

971
 AWS IoT API Reference
Statistics

Type: Double

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

972
 AWS IoT API Reference
StepFunctionsAction

StepFunctionsAction
Service: AWS IoT

Starts execution of a Step Functions state machine.

Contents
executionNamePrefix

(Optional) A name will be given to the state machine execution consisting of this prefix followed by a
UUID. Step Functions automatically creates a unique name for each state machine execution if one is
not provided.

Type: String

Required: No
roleArn

The ARN of the role that grants IoT permission to start execution of a state machine
("Action":"states:StartExecution").

Type: String

Required: Yes
stateMachineName

The name of the Step Functions state machine whose execution will be started.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

973
 AWS IoT API Reference
Stream

Stream
Service: AWS IoT

Describes a group of files that can be streamed.

Contents
fileId

The ID of a file associated with a stream.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 255.

Required: No
streamId

The stream ID.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

974
 AWS IoT API Reference
StreamFile

StreamFile
Service: AWS IoT

Represents a file to stream.

Contents
fileId

The file ID.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 255.

Required: No
s3Location

The location of the file in S3.

Type: S3Location (p. 957) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

975
 AWS IoT API Reference
StreamInfo

StreamInfo
Service: AWS IoT

Information about a stream.

Contents
createdAt

The date when the stream was created.

Type: Timestamp

Required: No
description

The description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files

The files to stream.

Type: Array of StreamFile (p. 975) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: No
lastUpdatedAt

The date when the stream was last updated.

Type: Timestamp

Required: No
roleArn

An IAM role AWS IoT assumes to access your S3 files.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
streamArn

The stream ARN.

Type: String

Required: No
streamId

The stream ID.

976
 AWS IoT API Reference
StreamInfo

Type: String

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

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

Required: No
streamVersion

The stream version.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 65535.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

977
 AWS IoT API Reference
StreamSummary

StreamSummary
Service: AWS IoT

A summary of a stream.

Contents
description

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
streamArn

The stream ARN.

Type: String

Required: No
streamId

The stream ID.

Type: String

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

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

Required: No
streamVersion

The stream version.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 65535.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

978
 AWS IoT API Reference
Tag

Tag
Service: AWS IoT

A set of key/value pairs that are used to manage the resource.

Contents
Key

The tag's key.

Type: String

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

Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: Yes
Value

The tag's value.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

979
 AWS IoT API Reference
TaskStatistics

TaskStatistics
Service: AWS IoT

Statistics for the checks performed during the audit.

Contents
canceledChecks

The number of checks that did not run because the audit was canceled.

Type: Integer

Required: No
compliantChecks

The number of checks that found compliant resources.

Type: Integer

Required: No
failedChecks

The number of checks.

Type: Integer

Required: No
inProgressChecks

The number of checks in progress.

Type: Integer

Required: No
nonCompliantChecks

The number of checks that found noncompliant resources.

Type: Integer

Required: No
totalChecks

The number of checks in this audit.

Type: Integer

Required: No
waitingForDataCollectionChecks

The number of checks waiting for data collection.

Type: Integer

Required: No

980
 AWS IoT API Reference
TaskStatistics

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

981
 AWS IoT API Reference
TaskStatisticsForAuditCheck

TaskStatisticsForAuditCheck
Service: AWS IoT

Provides summary counts of how many tasks for findings are in a particular state. This information is
included in the response from DescribeAuditMitigationActionsTask.

Contents
canceledFindingsCount

The number of findings to which the mitigation action task was canceled when applied.

Type: Long

Required: No
failedFindingsCount

The number of findings for which at least one of the actions failed when applied.

Type: Long

Required: No
skippedFindingsCount

The number of findings skipped because of filter conditions provided in the parameters to the
command.

Type: Long

Required: No
succeededFindingsCount

The number of findings for which all mitigation actions succeeded when applied.

Type: Long

Required: No
totalFindingsCount

The total number of findings to which a task is being applied.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

982
 AWS IoT API Reference
TermsAggregation

TermsAggregation
Service: AWS IoT

Performs an aggregation that will return a list of buckets. The list of buckets is a ranked list of the
number of occurrences of an aggregation field value.

Contents
maxBuckets

The number of buckets to return in the response. Default to 10.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 10000.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

983
 AWS IoT API Reference
ThingAttribute

ThingAttribute
Service: AWS IoT

The properties of the thing, including thing name, thing type name, and a list of thing attributes.

Contents
attributes

A list of thing attributes which are name-value pairs.

Type: String to string map

Key Length Constraints: Maximum length of 128.

Key Pattern: [a-zA-Z0-9_.,@/:#-]+

Value Length Constraints: Maximum length of 800.

Value Pattern: [a-zA-Z0-9_.,@/:#-]*

Required: No
thingArn

The thing ARN.

Type: String

Required: No
thingName

The name of the thing.

Type: String

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

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

Required: No
thingTypeName

The name of the thing type, if the thing has been associated with a type.

Type: String

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

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

Required: No
version

The version of the thing record in the registry.

Type: Long

Required: No

984
 AWS IoT API Reference
ThingAttribute

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

985
 AWS IoT API Reference
ThingConnectivity

ThingConnectivity
Service: AWS IoT

The connectivity status of the thing.

Contents
connected

True if the thing is connected to the AWS IoT Core service; false if it is not connected.

Type: Boolean

Required: No
disconnectReason

The reason why the client is disconnected. If the thing has been disconnected for approximately an
hour, the disconnectReason value might be missing.

Type: String

Required: No
timestamp

The epoch time (in milliseconds) when the thing last connected or disconnected. If the thing has
been disconnected for approximately an hour, the time value might be missing.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

986
 AWS IoT API Reference
ThingDocument

ThingDocument
Service: AWS IoT

The thing search index document.

Contents
attributes

The attributes.

Type: String to string map

Key Length Constraints: Maximum length of 128.

Key Pattern: [a-zA-Z0-9_.,@/:#-]+

Value Length Constraints: Maximum length of 800.

Value Pattern: [a-zA-Z0-9_.,@/:#-]*

Required: No
connectivity

Indicates whether the thing is connected to the AWS IoT Core service.

Type: ThingConnectivity (p. 986) object

Required: No
shadow

The shadow.

Type: String

Required: No
thingGroupNames

Thing group names.

Type: Array of strings

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

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

Required: No
thingId

The thing ID.

Type: String

Required: No
thingName

The thing name.

Type: String

987
 AWS IoT API Reference
ThingDocument

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

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

Required: No
thingTypeName

The thing type name.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

988
 AWS IoT API Reference
ThingGroupDocument

ThingGroupDocument
Service: AWS IoT

The thing group search index document.

Contents
attributes

The thing group attributes.

Type: String to string map

Key Length Constraints: Maximum length of 128.

Key Pattern: [a-zA-Z0-9_.,@/:#-]+

Value Length Constraints: Maximum length of 800.

Value Pattern: [a-zA-Z0-9_.,@/:#-]*

Required: No
parentGroupNames

Parent group names.

Type: Array of strings

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

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

Required: No
thingGroupDescription

The thing group description.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [\p{Graph}\x20]*

Required: No
thingGroupId

The thing group ID.

Type: String

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

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

Required: No
thingGroupName

The thing group name.

Type: String

989
 AWS IoT API Reference
ThingGroupDocument

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

990
 AWS IoT API Reference
ThingGroupIndexingConfiguration

ThingGroupIndexingConfiguration
Service: AWS IoT

Thing group indexing configuration.

Contents
customFields

A list of thing group fields to index. This list cannot contain any managed fields. Use the
GetIndexingConfiguration API to get a list of managed fields.

Contains custom field names and their data type.

Type: Array of Field (p. 871) objects

Required: No
managedFields

Contains fields that are indexed and whose types are already known by the Fleet Indexing service.

Type: Array of Field (p. 871) objects

Required: No
thingGroupIndexingMode

Thing group indexing mode.

Type: String

Valid Values: OFF | ON

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

991
 AWS IoT API Reference
ThingGroupMetadata

ThingGroupMetadata
Service: AWS IoT

Thing group metadata.

Contents
creationDate

The UNIX timestamp of when the thing group was created.

Type: Timestamp

Required: No
parentGroupName

The parent thing group name.

Type: String

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

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

Required: No
rootToParentThingGroups

The root parent thing group.

Type: Array of GroupNameAndArn (p. 875) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

992
 AWS IoT API Reference
ThingGroupProperties

ThingGroupProperties
Service: AWS IoT

Thing group properties.

Contents
attributePayload

The thing group attributes in JSON format.

Type: AttributePayload (p. 797) object

Required: No
thingGroupDescription

The thing group description.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [\p{Graph}\x20]*

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

993
 AWS IoT API Reference
ThingIndexingConfiguration

ThingIndexingConfiguration
Service: AWS IoT

The thing indexing configuration. For more information, see Managing Thing Indexing.

Contents
customFields

Contains custom field names and their data type.

Type: Array of Field (p. 871) objects

Required: No
managedFields

Contains fields that are indexed and whose types are already known by the Fleet Indexing service.

Type: Array of Field (p. 871) objects

Required: No
thingConnectivityIndexingMode

Thing connectivity indexing mode. Valid values are:

• STATUS – Your thing index contains connectivity status. To enable thing connectivity indexing,
thingIndexMode must not be set to OFF.
• OFF - Thing connectivity status indexing is disabled.

Type: String

Valid Values: OFF | STATUS

Required: No
thingIndexingMode

Thing indexing mode. Valid values are:

• REGISTRY – Your thing index contains registry data only.
• REGISTRY_AND_SHADOW - Your thing index contains registry and shadow data.
• OFF - Thing indexing is disabled.

Type: String

Valid Values: OFF | REGISTRY | REGISTRY_AND_SHADOW

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

994
 AWS IoT API Reference
ThingIndexingConfiguration

995
 AWS IoT API Reference
ThingTypeDefinition

ThingTypeDefinition
Service: AWS IoT

The definition of the thing type, including thing type name and description.

Contents
thingTypeArn

The thing type ARN.

Type: String

Required: No
thingTypeMetadata

The ThingTypeMetadata contains additional information about the thing type including: creation
date and time, a value indicating whether the thing type is deprecated, and a date and time when it
was deprecated.

Type: ThingTypeMetadata (p. 997) object

Required: No
thingTypeName

The name of the thing type.

Type: String

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

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

Required: No
thingTypeProperties

The ThingTypeProperties for the thing type.

Type: ThingTypeProperties (p. 998) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

996
 AWS IoT API Reference
ThingTypeMetadata

ThingTypeMetadata
Service: AWS IoT

The ThingTypeMetadata contains additional information about the thing type including: creation date
and time, a value indicating whether the thing type is deprecated, and a date and time when time was
deprecated.

Contents
creationDate

The date and time when the thing type was created.

Type: Timestamp

Required: No
deprecated

Whether the thing type is deprecated. If true, no new things could be associated with this type.

Type: Boolean

Required: No
deprecationDate

The date and time when the thing type was deprecated.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

997
 AWS IoT API Reference
ThingTypeProperties

ThingTypeProperties
Service: AWS IoT

The ThingTypeProperties contains information about the thing type including: a thing type description,
and a list of searchable thing attribute names.

Contents
searchableAttributes

A list of searchable thing attribute names.

Type: Array of strings

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_.,@/:#-]+

Required: No
thingTypeDescription

The description of the thing type.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [\p{Graph}\x20]*

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

998
 AWS IoT API Reference
TimeoutConfig

TimeoutConfig
Service: AWS IoT

Specifies the amount of time each device has to finish its execution of the job. A timer is started when
the job execution status is set to IN_PROGRESS. If the job execution status is not set to another terminal
state before the timer expires, it will be automatically set to TIMED_OUT.

Contents
inProgressTimeoutInMinutes

Specifies the amount of time, in minutes, this device has to finish execution of this job. The timeout
interval can be anywhere between 1 minute and 7 days (1 to 10080 minutes). The in progress timer
can't be updated and will apply to all job executions for the job. Whenever a job execution remains
in the IN_PROGRESS status for longer than this interval, the job execution will fail and switch to the
terminal TIMED_OUT status.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

999
 AWS IoT API Reference
TimestreamAction

TimestreamAction
Service: AWS IoT

The Timestream rule action writes attributes (measures) from an MQTT message into an Amazon
Timestream table. For more information, see the Timestream topic rule action documentation.

Contents
databaseName

The name of an Amazon Timestream database.

Type: String

Required: Yes
dimensions

Metadata attributes of the time series that are written in each measure record.

Type: Array of TimestreamDimension (p. 1002) objects

Array Members: Minimum number of 1 item. Maximum number of 128 items.

Required: Yes
roleArn

The ARN of the role that grants permission to write to the Amazon Timestream database table.

Type: String

Required: Yes
tableName

The name of the database table into which to write the measure records.

Type: String

Required: Yes
timestamp

Specifies an application-defined value to replace the default value assigned to the Timestream
record's timestamp in the time column.

You can use this property to specify the value and the precision of the Timestream record's
timestamp. You can specify a value from the message payload or a value computed by a substitution
template.

If omitted, the topic rule action assigns the timestamp, in milliseconds, at the time it processed the
rule.

Type: TimestreamTimestamp (p. 1003) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

1000
 AWS IoT API Reference
TimestreamAction

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1001
 AWS IoT API Reference
TimestreamDimension

TimestreamDimension
Service: AWS IoT

Metadata attributes of the time series that are written in each measure record.

Contents
name

The metadata dimension name. This is the name of the column in the Amazon Timestream database
table record.

Dimensions cannot be named: measure_name, measure_value, or time. These names are

reserved. Dimension names cannot start with ts_ or measure_value and they cannot contain the
colon (:) character.

Type: String

Required: Yes
value

The value to write in this column of the database record.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1002
 AWS IoT API Reference
TimestreamTimestamp

TimestreamTimestamp
Service: AWS IoT

Describes how to interpret an application-defined timestamp value from an MQTT message payload and
the precision of that value.

Contents
unit

The precision of the timestamp value that results from the expression described in value.

Valid values: SECONDS | MILLISECONDS | MICROSECONDS | NANOSECONDS. The default is

MILLISECONDS.

Type: String

Required: Yes
value

An expression that returns a long epoch time value.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1003
 AWS IoT API Reference
TlsContext

TlsContext
Service: AWS IoT

Specifies the TLS context to use for the test authorizer request.

Contents
serverName

The value of the serverName key in a TLS authorization request.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1004
 AWS IoT API Reference
TopicRule

TopicRule
Service: AWS IoT

Describes a rule.

Contents
actions

The actions associated with the rule.

Type: Array of Action (p. 785) objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: No
awsIotSqlVersion

The version of the SQL rules engine to use when evaluating the rule.

Type: String

Required: No
createdAt

The date and time the rule was created.

Type: Timestamp

Required: No
description

The description of the rule.

Type: String

Required: No
errorAction

The action to perform when an error occurs.

Type: Action (p. 785) object

Required: No
ruleDisabled

Specifies whether the rule is disabled.

Type: Boolean

Required: No
ruleName

The name of the rule.

Type: String

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

1005
 AWS IoT API Reference
TopicRule

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

Required: No
sql

The SQL statement used to query the topic. When using a SQL query with multiple lines, be sure to
escape the newline characters.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1006
 AWS IoT API Reference
TopicRuleDestination

TopicRuleDestination
Service: AWS IoT

A topic rule destination.

Contents
arn

The topic rule destination URL.

Type: String

Required: No
createdAt

The date and time when the topic rule destination was created.

Type: Timestamp

Required: No
httpUrlProperties

Properties of the HTTP URL.

Type: HttpUrlDestinationProperties (p. 882) object

Required: No
lastUpdatedAt

The date and time when the topic rule destination was last updated.

Type: Timestamp

Required: No
status

The status of the topic rule destination. Valid values are:

IN_PROGRESS

A topic rule destination was created but has not been confirmed. You can set
status to IN_PROGRESS by calling UpdateTopicRuleDestination. Calling
UpdateTopicRuleDestination causes a new confirmation challenge to be sent to your
confirmation endpoint.
ENABLED

Confirmation was completed, and traffic to this destination is allowed. You can set status to
DISABLED by calling UpdateTopicRuleDestination.
DISABLED

Confirmation was completed, and traffic to this destination is not allowed. You can set status
to ENABLED by calling UpdateTopicRuleDestination.
ERROR

Confirmation could not be completed, for example if the confirmation timed out. You can call
GetTopicRuleDestination for details about the error. You can set status to IN_PROGRESS

1007
 AWS IoT API Reference
TopicRuleDestination

by calling UpdateTopicRuleDestination. Calling UpdateTopicRuleDestination causes a

new confirmation challenge to be sent to your confirmation endpoint.

Type: String

Valid Values: ENABLED | IN_PROGRESS | DISABLED | ERROR | DELETING

Required: No
statusReason

Additional details or reason why the topic rule destination is in the current status.

Type: String

Required: No
vpcProperties

Properties of the virtual private cloud (VPC) connection.

Type: VpcDestinationProperties (p. 1024) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1008
 AWS IoT API Reference
TopicRuleDestinationConfiguration

TopicRuleDestinationConfiguration
Service: AWS IoT

Configuration of the topic rule destination.

Contents
httpUrlConfiguration

Configuration of the HTTP URL.

Type: HttpUrlDestinationConfiguration (p. 881) object

Required: No
vpcConfiguration

Configuration of the virtual private cloud (VPC) connection.

Type: VpcDestinationConfiguration (p. 1023) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1009
 AWS IoT API Reference
TopicRuleDestinationSummary

TopicRuleDestinationSummary
Service: AWS IoT

Information about the topic rule destination.

Contents
arn

The topic rule destination ARN.

Type: String

Required: No
createdAt

The date and time when the topic rule destination was created.

Type: Timestamp

Required: No
httpUrlSummary

Information about the HTTP URL.

Type: HttpUrlDestinationSummary (p. 883) object

Required: No
lastUpdatedAt

The date and time when the topic rule destination was last updated.

Type: Timestamp

Required: No
status

The status of the topic rule destination. Valid values are:

IN_PROGRESS

A topic rule destination was created but has not been confirmed. You can set
status to IN_PROGRESS by calling UpdateTopicRuleDestination. Calling
UpdateTopicRuleDestination causes a new confirmation challenge to be sent to your
confirmation endpoint.
ENABLED

Confirmation was completed, and traffic to this destination is allowed. You can set status to
DISABLED by calling UpdateTopicRuleDestination.
DISABLED

Confirmation was completed, and traffic to this destination is not allowed. You can set status
to ENABLED by calling UpdateTopicRuleDestination.
ERROR

Confirmation could not be completed, for example if the confirmation timed out. You can call
GetTopicRuleDestination for details about the error. You can set status to IN_PROGRESS

1010
 AWS IoT API Reference
TopicRuleDestinationSummary

by calling UpdateTopicRuleDestination. Calling UpdateTopicRuleDestination causes a

new confirmation challenge to be sent to your confirmation endpoint.

Type: String

Valid Values: ENABLED | IN_PROGRESS | DISABLED | ERROR | DELETING

Required: No
statusReason

The reason the topic rule destination is in the current status.

Type: String

Required: No
vpcDestinationSummary

Information about the virtual private cloud (VPC) connection.

Type: VpcDestinationSummary (p. 1025) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1011
 AWS IoT API Reference
TopicRuleListItem

TopicRuleListItem
Service: AWS IoT

Describes a rule.

Contents
createdAt

The date and time the rule was created.

Type: Timestamp

Required: No
ruleArn

The rule ARN.

Type: String

Required: No
ruleDisabled

Specifies whether the rule is disabled.

Type: Boolean

Required: No
ruleName

The name of the rule.

Type: String

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

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

Required: No
topicPattern

The pattern for the topic names that apply.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1012
 AWS IoT API Reference
TopicRulePayload

TopicRulePayload
Service: AWS IoT

Describes a rule.

Contents
actions

The actions associated with the rule.

Type: Array of Action (p. 785) objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: Yes
awsIotSqlVersion

The version of the SQL rules engine to use when evaluating the rule.

Type: String

Required: No
description

The description of the rule.

Type: String

Required: No
errorAction

The action to take when an error occurs.

Type: Action (p. 785) object

Required: No
ruleDisabled

Specifies whether the rule is disabled.

Type: Boolean

Required: No
sql

The SQL statement used to query the topic. For more information, see AWS IoT SQL Reference in
the AWS IoT Developer Guide.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

1013
 AWS IoT API Reference
TopicRulePayload

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1014
 AWS IoT API Reference
TransferData

TransferData
Service: AWS IoT

Data used to transfer a certificate to an AWS account.

Contents
acceptDate

The date the transfer was accepted.

Type: Timestamp

Required: No
rejectDate

The date the transfer was rejected.

Type: Timestamp

Required: No
rejectReason

The reason why the transfer was rejected.

Type: String

Length Constraints: Maximum length of 128.

Required: No
transferDate

The date the transfer took place.

Type: Timestamp

Required: No
transferMessage

The transfer message.

Type: String

Length Constraints: Maximum length of 128.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1015
 AWS IoT API Reference
UpdateCACertificateParams

UpdateCACertificateParams
Service: AWS IoT

Parameters to define a mitigation action that changes the state of the CA certificate to inactive.

Contents
action

The action that you want to apply to the CA certificate. The only supported value is DEACTIVATE.

Type: String

Valid Values: DEACTIVATE

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1016
 AWS IoT API Reference
UpdateDeviceCertificateParams

UpdateDeviceCertificateParams
Service: AWS IoT

Parameters to define a mitigation action that changes the state of the device certificate to inactive.

Contents
action

The action that you want to apply to the device certificate. The only supported value is
DEACTIVATE.

Type: String

Valid Values: DEACTIVATE

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1017
 AWS IoT API Reference
ValidationError

ValidationError
Service: AWS IoT

Information about an error found in a behavior specification.

Contents
errorMessage

The description of an error found in the behaviors.

Type: String

Length Constraints: Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1018
 AWS IoT API Reference
ViolationEvent

ViolationEvent
Service: AWS IoT

Information about a Device Defender security profile behavior violation.

Contents
behavior

The behavior that was violated.

Type: Behavior (p. 825) object

Required: No
metricValue

The value of the metric (the measurement).

Type: MetricValue (p. 917) object

Required: No
securityProfileName

The name of the security profile whose behavior was violated.

Type: String

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

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

Required: No
thingName

The name of the thing responsible for the violation event.

Type: String

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

Required: No
violationEventAdditionalInfo

The details of a violation event.

Type: ViolationEventAdditionalInfo (p. 1021) object

Required: No
violationEventTime

The time the violation event occurred.

Type: Timestamp

Required: No
violationEventType

The type of violation event.

1019
 AWS IoT API Reference
ViolationEvent

Type: String

Valid Values: in-alarm | alarm-cleared | alarm-invalidated

Required: No
violationId

The ID of the violation event.

Type: String

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

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1020
 AWS IoT API Reference
ViolationEventAdditionalInfo

ViolationEventAdditionalInfo
Service: AWS IoT

The details of a violation event.

Contents
confidenceLevel

The sensitivity of anomalous behavior evaluation. Can be Low, Medium, or High.

Type: String

Valid Values: LOW | MEDIUM | HIGH

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1021
 AWS IoT API Reference
ViolationEventOccurrenceRange

ViolationEventOccurrenceRange
Service: AWS IoT

Specifies the time period of which violation events occurred between.

Contents
endTime

The end date and time of a time period in which violation events occurred.

Type: Timestamp

Required: Yes
startTime

The start date and time of a time period in which violation events occurred.

Type: Timestamp

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1022
 AWS IoT API Reference
VpcDestinationConfiguration

VpcDestinationConfiguration
Service: AWS IoT

The configuration information for a virtual private cloud (VPC) destination.

Contents
roleArn

The ARN of a role that has permission to create and attach to elastic network interfaces (ENIs).

Type: String

Required: Yes
securityGroups

The security groups of the VPC destination.

Type: Array of strings

Required: No
subnetIds

The subnet IDs of the VPC destination.

Type: Array of strings

Required: Yes
vpcId

The ID of the VPC.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1023
 AWS IoT API Reference
VpcDestinationProperties

VpcDestinationProperties
Service: AWS IoT

The properties of a virtual private cloud (VPC) destination.

Contents
roleArn

The ARN of a role that has permission to create and attach to elastic network interfaces (ENIs).

Type: String

Required: No
securityGroups

The security groups of the VPC destination.

Type: Array of strings

Required: No
subnetIds

The subnet IDs of the VPC destination.

Type: Array of strings

Required: No
vpcId

The ID of the VPC.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1024
 AWS IoT API Reference
VpcDestinationSummary

VpcDestinationSummary
Service: AWS IoT

The summary of a virtual private cloud (VPC) destination.

Contents
roleArn

The ARN of a role that has permission to create and attach to elastic network interfaces (ENIs).

Type: String

Required: No
securityGroups

The security groups of the VPC destination.

Type: Array of strings

Required: No
subnetIds

The subnet IDs of the VPC destination.

Type: Array of strings

Required: No
vpcId

The ID of the VPC.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

AWS IoT data

The following data types are supported by AWS IoT data:

• RetainedMessageSummary (p. 1026)

1025
 AWS IoT API Reference
RetainedMessageSummary

RetainedMessageSummary
Service: AWS IoT data

Information about a single retained message.

Contents
lastModifiedTime

The Epoch date and time, in milliseconds, when the retained message was stored by AWS IoT.

Type: Long

Required: No
payloadSize

The size of the retained message's payload in bytes.

Type: Long

Required: No
qos

The quality of service (QoS) level used to publish the retained message.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 1.

Required: No
topic

The topic name to which the retained message was published.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

AWS IoT jobs data

The following data types are supported by AWS IoT jobs data:

• JobExecution (p. 1028)

• JobExecutionState (p. 1031)
• JobExecutionSummary (p. 1032)

1026
AWS IoT API Reference
AWS IoT jobs data

1027
 AWS IoT API Reference
JobExecution

JobExecution
Service: AWS IoT jobs data

Contains data about a job execution.

Contents
approximateSecondsBeforeTimedOut

The estimated number of seconds that remain before the job execution status will be changed to
TIMED_OUT. The actual job execution timeout can occur up to 60 seconds later than the estimated
duration.

Type: Long

Required: No
executionNumber

A number that identifies a particular job execution on a particular device. It can be used later in
commands that return or update job execution information.

Type: Long

Required: No
jobDocument

The content of the job document.

Type: String

Length Constraints: Maximum length of 32768.

Required: No
jobId

The unique identifier you assigned to this job when it was created.

Type: String

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

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

Required: No
lastUpdatedAt

The time, in seconds since the epoch, when the job execution was last updated.

Type: Long

Required: No
queuedAt

The time, in seconds since the epoch, when the job execution was enqueued.

Type: Long

Required: No

1028
 AWS IoT API Reference
JobExecution

startedAt

The time, in seconds since the epoch, when the job execution was started.

Type: Long

Required: No
status

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS",
"CANCELED", "TIMED_OUT", "REJECTED", or "REMOVED".

Type: String

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED

Required: No
statusDetails

A collection of name/value pairs that describe the status of the job execution.

The maximum length of the value in the name/value pair is 1,024 characters.

Type: String to string map

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

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

Value Length Constraints: Minimum length of 1.

Value Pattern: [^\p{C}]+

Required: No
thingName

The name of the thing that is executing the job.

Type: String

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

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

Required: No
versionNumber

The version of the job execution. Job execution versions are incremented each time they are updated
by a device.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

1029
 AWS IoT API Reference
JobExecution

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1030
 AWS IoT API Reference
JobExecutionState

JobExecutionState
Service: AWS IoT jobs data

Contains data about the state of a job execution.

Contents
status

The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS",
"CANCELED", "TIMED_OUT", "REJECTED", or "REMOVED".

Type: String

Valid Values: QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | TIMED_OUT | REJECTED

| REMOVED | CANCELED

Required: No
statusDetails

A collection of name/value pairs that describe the status of the job execution.

The maximum length of the value in the name/value pair is 1,024 characters.

Type: String to string map

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

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

Value Length Constraints: Minimum length of 1.

Value Pattern: [^\p{C}]+

Required: No
versionNumber

The version of the job execution. Job execution versions are incremented each time they are updated
by a device.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1031
 AWS IoT API Reference
JobExecutionSummary

JobExecutionSummary
Service: AWS IoT jobs data

Contains a subset of information about a job execution.

Contents
executionNumber

A number that identifies a particular job execution on a particular device.

Type: Long

Required: No
jobId

The unique identifier you assigned to this job when it was created.

Type: String

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

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

Required: No
lastUpdatedAt

The time, in seconds since the epoch, when the job execution was last updated.

Type: Long

Required: No
queuedAt

The time, in seconds since the epoch, when the job execution was enqueued.

Type: Long

Required: No
startedAt

The time, in seconds since the epoch, when the job execution started.

Type: Long

Required: No
versionNumber

The version of the job execution. Job execution versions are incremented each time AWS IoT Jobs
receives an update from a device.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

1032
 AWS IoT API Reference
AWS IoT Core Device Advisor

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

AWS IoT Core Device Advisor

The following data types are supported by AWS IoT Core Device Advisor:

• DeviceUnderTest (p. 1034)

• GroupResult (p. 1035)
• SuiteDefinitionConfiguration (p. 1036)
• SuiteDefinitionInformation (p. 1038)
• SuiteRunConfiguration (p. 1040)
• SuiteRunInformation (p. 1041)
• TestCaseRun (p. 1043)
• TestResult (p. 1045)

1033
 AWS IoT API Reference
DeviceUnderTest

DeviceUnderTest
Service: AWS IoT Core Device Advisor

Information of a test device. Required to provide either a thing ARN or a certificate ARN.

Contents
certificateArn

Lists devices certificate ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
thingArn

Lists devices thing ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1034
 AWS IoT API Reference
GroupResult

GroupResult
Service: AWS IoT Core Device Advisor

Show Group Result.

Contents
groupId

Group result ID.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
groupName

Group Result Name.

Type: String

Required: No
tests

Tests under Group Result.

Type: Array of TestCaseRun (p. 1043) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1035
 AWS IoT API Reference
SuiteDefinitionConfiguration

SuiteDefinitionConfiguration
Service: AWS IoT Core Device Advisor

Gets Suite Definition Configuration.

Contents
devicePermissionRoleArn

Gets device permission ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
devices

Gets the devices configured.

Type: Array of DeviceUnderTest (p. 1034) objects

Array Members: Minimum number of 0 items. Maximum number of 2 items.

Required: No
intendedForQualification

Gets the tests intended for qualification in a suite.

Type: Boolean

Required: No
rootGroup

Gets test suite root group.

Type: String

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

Required: Yes
suiteDefinitionName

Gets Suite Definition Configuration name.

Type: String

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

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go

1036
 AWS IoT API Reference
SuiteDefinitionConfiguration

• AWS SDK for Java V2

• AWS SDK for Ruby V3

1037
 AWS IoT API Reference
SuiteDefinitionInformation

SuiteDefinitionInformation
Service: AWS IoT Core Device Advisor

Information about the suite definition.

Contents
createdAt

Date (in Unix epoch time) when the test suite was created.

Type: Timestamp

Required: No
defaultDevices

Specifies the devices under test for the test suite.

Type: Array of DeviceUnderTest (p. 1034) objects

Array Members: Minimum number of 0 items. Maximum number of 2 items.

Required: No
intendedForQualification

Specifies if the test suite is intended for qualification.

Type: Boolean

Required: No
suiteDefinitionId

Suite definition ID of the test suite.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
suiteDefinitionName

Suite name of the test suite.

Type: String

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

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1038
 AWS IoT API Reference
SuiteDefinitionInformation

1039
 AWS IoT API Reference
SuiteRunConfiguration

SuiteRunConfiguration
Service: AWS IoT Core Device Advisor

Gets suite run configuration.

Contents
primaryDevice

Gets the primary device for suite run.

Type: DeviceUnderTest (p. 1034) object

Required: Yes
selectedTestList

Gets test case list.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 100 items.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1040
 AWS IoT API Reference
SuiteRunInformation

SuiteRunInformation
Service: AWS IoT Core Device Advisor

Information about the suite run.

Requires permission to access the SuiteRunInformation action.

Contents
createdAt

Date (in Unix epoch time) when the suite run was created.

Type: Timestamp

Required: No
endAt

Date (in Unix epoch time) when the suite run ended.

Type: Timestamp

Required: No
failed

Number of test cases that failed in the suite run.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 500.

Required: No
passed

Number of test cases that passed in the suite run.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 500.

Required: No
startedAt

Date (in Unix epoch time) when the suite run was started.

Type: Timestamp

Required: No
status

Status of the suite run.

Type: String

Valid Values: PASS | FAIL | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR

Required: No

1041
 AWS IoT API Reference
SuiteRunInformation

suiteDefinitionId

Suite definition ID of the suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
suiteDefinitionName

Suite definition name of the suite run.

Type: String

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

Required: No
suiteDefinitionVersion

Suite definition version of the suite run.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

Required: No
suiteRunId

Suite run ID of the suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1042
 AWS IoT API Reference
TestCaseRun

TestCaseRun
Service: AWS IoT Core Device Advisor

Provides test case run.

Contents
endTime

Provides test case run end time.

Type: Timestamp

Required: No
failure

Provides test case run failure result.

Type: String

Required: No
logUrl

Provides test case run log Url.

Type: String

Required: No
startTime

Provides test case run start time.

Type: Timestamp

Required: No
status

Provides test case run status.

• PASS: Test passed.
• FAIL: Test failed.
• PENDING: Test has not started running but is scheduled.
• RUNNING: Test is running
• STOPPING: Test is performing cleanup steps. You will see this status only if you stop a suite run.
• STOPPED Test is stopped. You will see this status only if you stop a suite run.
• PASS_WITH_WARNINGS: Test passed with warnings.
• ERORR: Test faced an error when running due to an internal issue.

Type: String

Valid Values: PASS | FAIL | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR

Required: No
testCaseDefinitionId

Provides test case run definition ID.

1043
 AWS IoT API Reference
TestCaseRun

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
testCaseDefinitionName

Provides test case run definition Name.

Type: String

Required: No
testCaseRunId

Provides test case run ID.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
warnings

Provides test case run warnings.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1044
 AWS IoT API Reference
TestResult

TestResult
Service: AWS IoT Core Device Advisor

Show each group result.

Contents
groups

Show each group of test results.

Type: Array of GroupResult (p. 1035) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

AWS IoT Fleet Hub

The following data types are supported by AWS IoT Fleet Hub:

• ApplicationSummary (p. 1046)

1045
 AWS IoT API Reference
ApplicationSummary

ApplicationSummary
Service: AWS IoT Fleet Hub

A summary of information about a Fleet Hub for AWS IoT Device Management web application.

Contents
applicationCreationDate

The date (in Unix epoch time) when the web application was created.

Type: Long

Required: No
applicationDescription

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No
applicationId

The unique Id of the web application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Required: Yes
applicationLastUpdateDate

The date (in Unix epoch time) when the web application was last updated.

Type: Long

Required: No
applicationName

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: Yes
applicationState

The current state of the web application.

Type: String

1046
 AWS IoT API Reference
AWS IoT Secure Tunneling

Valid Values: CREATING | DELETING | ACTIVE | CREATE_FAILED | DELETE_FAILED

Required: No
applicationUrl

The URL of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: ^https\://\S+$

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

AWS IoT Secure Tunneling

The following data types are supported by AWS IoT Secure Tunneling:

• ConnectionState (p. 1048)

• DestinationConfig (p. 1049)
• Tag (p. 1050)
• TimeoutConfig (p. 1051)
• Tunnel (p. 1052)
• TunnelSummary (p. 1054)

1047
 AWS IoT API Reference
ConnectionState

ConnectionState
Service: AWS IoT Secure Tunneling

The state of a connection.

Contents
lastUpdatedAt

The last time the connection status was updated.

Type: Timestamp

Required: No
status

The connection status of the tunnel. Valid values are CONNECTED and DISCONNECTED.

Type: String

Valid Values: CONNECTED | DISCONNECTED

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1048
 AWS IoT API Reference
DestinationConfig

DestinationConfig
Service: AWS IoT Secure Tunneling

The destination configuration.

Contents
services

A list of service names that identify the target application. The AWS IoT client running on the
destination device reads this value and uses it to look up a port or an IP address and a port. The
AWS IoT client instantiates the local proxy, which uses this information to connect to the destination
application.

Type: Array of strings

Array Members: Minimum number of 1 item.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: Yes
thingName

The name of the IoT thing to which you want to connect.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1049
 AWS IoT API Reference
Tag

Tag
Service: AWS IoT Secure Tunneling

An arbitary key/value pair used to add searchable metadata to secure tunnel resources.

Contents
key

The key of the tag.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: Yes
value

The value of the tag.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1050
 AWS IoT API Reference
TimeoutConfig

TimeoutConfig
Service: AWS IoT Secure Tunneling

Tunnel timeout configuration.

Contents
maxLifetimeTimeoutMinutes

The maximum amount of time (in minutes) a tunnel can remain open. If not specified,
maxLifetimeTimeoutMinutes defaults to 720 minutes. Valid values are from 1 minute to 12 hours
(720 minutes)

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 720.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1051
 AWS IoT API Reference
Tunnel

Tunnel
Service: AWS IoT Secure Tunneling

A connection between a source computer and a destination device.

Contents
createdAt

The time when the tunnel was created.

Type: Timestamp

Required: No
description

A description of the tunnel.

Type: String

Pattern: [^\p{C}]{1,2048}

Required: No
destinationConfig

The destination configuration that specifies the thing name of the destination device and a service
name that the local proxy uses to connect to the destination application.

Type: DestinationConfig (p. 1049) object

Required: No
destinationConnectionState

The connection state of the destination application.

Type: ConnectionState (p. 1048) object

Required: No
lastUpdatedAt

The last time the tunnel was updated.

Type: Timestamp

Required: No
sourceConnectionState

The connection state of the source application.

Type: ConnectionState (p. 1048) object

Required: No
status

The status of a tunnel. Valid values are: Open and Closed.

Type: String

Valid Values: OPEN | CLOSED

1052
 AWS IoT API Reference
Tunnel

Required: No
tags

A list of tag metadata associated with the secure tunnel.

Type: Array of Tag (p. 1050) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

Required: No
timeoutConfig

Timeout configuration for the tunnel.

Type: TimeoutConfig (p. 1051) object

Required: No
tunnelArn

The Amazon Resource Name (ARN) of a tunnel. The tunnel ARN format is
arn:aws:tunnel:<region>:<account-id>:tunnel/<tunnel-id>

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Required: No
tunnelId

A unique alpha-numeric ID that identifies a tunnel.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1053
 AWS IoT API Reference
TunnelSummary

TunnelSummary
Service: AWS IoT Secure Tunneling

Information about the tunnel.

Contents
createdAt

The time the tunnel was created.

Type: Timestamp

Required: No
description

A description of the tunnel.

Type: String

Pattern: [^\p{C}]{1,2048}

Required: No
lastUpdatedAt

The time the tunnel was last updated.

Type: Timestamp

Required: No
status

The status of a tunnel. Valid values are: Open and Closed.

Type: String

Valid Values: OPEN | CLOSED

Required: No
tunnelArn

The Amazon Resource Name of the tunnel. The tunnel ARN format is
arn:aws:tunnel:<region>:<account-id>:tunnel/<tunnel-id>

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Required: No
tunnelId

The unique alpha-numeric identifier for the tunnel.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Required: No

1054
 AWS IoT API Reference
TunnelSummary

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1055
 AWS IoT API Reference

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is

1056
 AWS IoT API Reference

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional

1057