AWS IoT

API Reference
 AWS IoT API Reference

AWS IoT: API Reference

Copyright © 2023 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

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 ................................................................................................... 16
AddThingToBillingGroup .................................................................................................... 18
AddThingToThingGroup ..................................................................................................... 21
AssociateTargetsWithJob ................................................................................................... 24
AttachPolicy .................................................................................................................... 27
AttachPrincipalPolicy ........................................................................................................ 29
AttachSecurityProfile ........................................................................................................ 31
AttachThingPrincipal ......................................................................................................... 33
CancelAuditMitigationActionsTask ....................................................................................... 35
CancelAuditTask ............................................................................................................... 37
CancelCertificateTransfer ................................................................................................... 39
CancelDetectMitigationActionsTask ..................................................................................... 41
CancelJob ........................................................................................................................ 43
CancelJobExecution .......................................................................................................... 46
ClearDefaultAuthorizer ...................................................................................................... 49
ConfirmTopicRuleDestination ............................................................................................. 51
CreateAuditSuppression ..................................................................................................... 53
CreateAuthorizer .............................................................................................................. 56
CreateBillingGroup ............................................................................................................ 60
CreateCertificateFromCsr ................................................................................................... 63
CreateCustomMetric .......................................................................................................... 66
CreateDimension .............................................................................................................. 69
CreateDomainConfiguration ............................................................................................... 72
CreateDynamicThingGroup ................................................................................................ 76
CreateFleetMetric ............................................................................................................. 80
CreateJob ........................................................................................................................ 85
CreateJobTemplate ........................................................................................................... 92
CreateKeysAndCertificate ................................................................................................... 97
CreateMitigationAction .................................................................................................... 100
CreateOTAUpdate ........................................................................................................... 103
CreatePackage ................................................................................................................ 109
CreatePackageVersion ..................................................................................................... 112
CreatePolicy ................................................................................................................... 116
CreatePolicyVersion ......................................................................................................... 119
CreateProvisioningClaim .................................................................................................. 122
CreateProvisioningTemplate ............................................................................................. 125
CreateProvisioningTemplateVersion ................................................................................... 129
CreateRoleAlias .............................................................................................................. 132
CreateScheduledAudit ..................................................................................................... 135
CreateSecurityProfile ....................................................................................................... 138
CreateStream ................................................................................................................. 142
CreateThing ................................................................................................................... 146
CreateThingGroup ........................................................................................................... 149
CreateThingType ............................................................................................................. 152
CreateTopicRule .............................................................................................................. 155

iii
 AWS IoT API Reference

CreateTopicRuleDestination .............................................................................................. 164

DeleteAccountAuditConfiguration ..................................................................................... 167
DeleteAuditSuppression ................................................................................................... 169
DeleteAuthorizer ............................................................................................................ 171
DeleteBillingGroup .......................................................................................................... 173
DeleteCACertificate ......................................................................................................... 175
DeleteCertificate ............................................................................................................. 177
DeleteCustomMetric ........................................................................................................ 179
DeleteDimension ............................................................................................................ 181
DeleteDomainConfiguration ............................................................................................. 183
DeleteDynamicThingGroup ............................................................................................... 185
DeleteFleetMetric ........................................................................................................... 187
DeleteJob ...................................................................................................................... 189
DeleteJobExecution ......................................................................................................... 192
DeleteJobTemplate ......................................................................................................... 195
DeleteMitigationAction .................................................................................................... 197
DeleteOTAUpdate ........................................................................................................... 199
DeletePackage ................................................................................................................ 201
DeletePackageVersion ..................................................................................................... 203
DeletePolicy ................................................................................................................... 205
DeletePolicyVersion ......................................................................................................... 207
DeleteProvisioningTemplate ............................................................................................. 209
DeleteProvisioningTemplateVersion ................................................................................... 211
DeleteRegistrationCode ................................................................................................... 213
DeleteRoleAlias .............................................................................................................. 215
DeleteScheduledAudit ..................................................................................................... 217
DeleteSecurityProfile ....................................................................................................... 219
DeleteStream ................................................................................................................. 221
DeleteThing ................................................................................................................... 223
DeleteThingGroup ........................................................................................................... 225
DeleteThingType ............................................................................................................. 227
DeleteTopicRule .............................................................................................................. 229
DeleteTopicRuleDestination .............................................................................................. 231
DeleteV2LoggingLevel ..................................................................................................... 233
DeprecateThingType ....................................................................................................... 235
DescribeAccountAuditConfiguration .................................................................................. 237
DescribeAuditFinding ...................................................................................................... 239
DescribeAuditMitigationActionsTask .................................................................................. 242
DescribeAuditSuppression ................................................................................................ 246
DescribeAuditTask ........................................................................................................... 249
DescribeAuthorizer .......................................................................................................... 252
DescribeBillingGroup ....................................................................................................... 254
DescribeCACertificate ...................................................................................................... 257
DescribeCertificate .......................................................................................................... 260
DescribeCustomMetric ..................................................................................................... 263
DescribeDefaultAuthorizer ............................................................................................... 266
DescribeDetectMitigationActionsTask ................................................................................ 268
DescribeDimension .......................................................................................................... 271
DescribeDomainConfiguration .......................................................................................... 274
DescribeEndpoint ............................................................................................................ 278
DescribeEventConfigurations ............................................................................................ 280
DescribeFleetMetric ......................................................................................................... 282
DescribeIndex ................................................................................................................. 286
DescribeJob ................................................................................................................... 289
DescribeJobExecution ...................................................................................................... 293
DescribeJobTemplate ...................................................................................................... 296
DescribeManagedJobTemplate ......................................................................................... 300

iv
 AWS IoT API Reference

DescribeMitigationAction ................................................................................................. 303

DescribeProvisioningTemplate .......................................................................................... 306
DescribeProvisioningTemplateVersion ................................................................................ 310
DescribeRoleAlias ............................................................................................................ 313
DescribeScheduledAudit .................................................................................................. 315
DescribeSecurityProfile .................................................................................................... 318
DescribeStream .............................................................................................................. 322
DescribeThing ................................................................................................................ 325
DescribeThingGroup ........................................................................................................ 328
DescribeThingRegistrationTask ......................................................................................... 332
DescribeThingType .......................................................................................................... 336
DetachPolicy .................................................................................................................. 339
DetachPrincipalPolicy ...................................................................................................... 341
DetachSecurityProfile ...................................................................................................... 343
DetachThingPrincipal ...................................................................................................... 345
DisableTopicRule ............................................................................................................ 347
EnableTopicRule ............................................................................................................. 349
GetBehaviorModelTrainingSummaries ................................................................................ 351
GetBucketsAggregation ................................................................................................... 353
GetCardinality ................................................................................................................ 357
GetEffectivePolicies ......................................................................................................... 360
GetIndexingConfiguration ................................................................................................ 363
GetJobDocument ............................................................................................................ 366
GetLoggingOptions ......................................................................................................... 368
GetOTAUpdate ............................................................................................................... 370
GetPackage .................................................................................................................... 374
GetPackageConfiguration ................................................................................................. 377
GetPackageVersion ......................................................................................................... 379
GetPercentiles ................................................................................................................ 383
GetPolicy ....................................................................................................................... 386
GetPolicyVersion ............................................................................................................. 389
GetRegistrationCode ....................................................................................................... 392
GetStatistics ................................................................................................................... 394
GetTopicRule .................................................................................................................. 397
GetTopicRuleDestination .................................................................................................. 406
GetV2LoggingOptions ..................................................................................................... 408
ListActiveViolations ......................................................................................................... 410
ListAttachedPolicies ........................................................................................................ 413
ListAuditFindings ............................................................................................................ 416
ListAuditMitigationActionsExecutions ................................................................................ 420
ListAuditMitigationActionsTasks ........................................................................................ 423
ListAuditSuppressions ...................................................................................................... 426
ListAuditTasks ................................................................................................................ 429
ListAuthorizers ............................................................................................................... 432
ListBillingGroups ............................................................................................................. 435
ListCACertificates ............................................................................................................ 437
ListCertificates ............................................................................................................... 440
ListCertificatesByCA ........................................................................................................ 443
ListCustomMetrics ........................................................................................................... 446
ListDetectMitigationActionsExecutions ............................................................................... 448
ListDetectMitigationActionsTasks ...................................................................................... 451
ListDimensions ............................................................................................................... 454
ListDomainConfigurations ................................................................................................ 456
ListFleetMetrics .............................................................................................................. 459
ListIndices ...................................................................................................................... 461
ListJobExecutionsForJob .................................................................................................. 463
ListJobExecutionsForThing ............................................................................................... 466

v
 AWS IoT API Reference

ListJobs ......................................................................................................................... 469

ListJobTemplates ............................................................................................................ 472
ListManagedJobTemplates ............................................................................................... 474
ListMetricValues ............................................................................................................. 476
ListMitigationActions ....................................................................................................... 479
ListOTAUpdates .............................................................................................................. 481
ListOutgoingCertificates .................................................................................................. 484
ListPackages .................................................................................................................. 487
ListPackageVersions ........................................................................................................ 489
ListPolicies ..................................................................................................................... 491
ListPolicyPrincipals .......................................................................................................... 494
ListPolicyVersions ........................................................................................................... 497
ListPrincipalPolicies ......................................................................................................... 499
ListPrincipalThings .......................................................................................................... 502
ListProvisioningTemplates ................................................................................................ 505
ListProvisioningTemplateVersions ..................................................................................... 507
ListRelatedResourcesForAuditFinding ................................................................................. 510
ListRoleAliases ................................................................................................................ 513
ListScheduledAudits ........................................................................................................ 516
ListSecurityProfiles .......................................................................................................... 518
ListSecurityProfilesForTarget ............................................................................................ 521
ListStreams .................................................................................................................... 524
ListTagsForResource ........................................................................................................ 526
ListTargetsForPolicy ........................................................................................................ 528
ListTargetsForSecurityProfile ............................................................................................ 531
ListThingGroups ............................................................................................................. 533
ListThingGroupsForThing ................................................................................................. 536
ListThingPrincipals .......................................................................................................... 538
ListThingRegistrationTaskReports ...................................................................................... 541
ListThingRegistrationTasks ............................................................................................... 544
ListThings ...................................................................................................................... 546
ListThingsInBillingGroup .................................................................................................. 549
ListThingsInThingGroup ................................................................................................... 551
ListThingTypes ............................................................................................................... 553
ListTopicRuleDestinations ................................................................................................ 556
ListTopicRules ................................................................................................................ 558
ListV2LoggingLevels ........................................................................................................ 560
ListViolationEvents ......................................................................................................... 562
PutVerificationStateOnViolation ....................................................................................... 566
RegisterCACertificate ....................................................................................................... 568
RegisterCertificate .......................................................................................................... 572
RegisterCertificateWithoutCA ........................................................................................... 575
RegisterThing ................................................................................................................. 578
RejectCertificateTransfer .................................................................................................. 581
RemoveThingFromBillingGroup ......................................................................................... 584
RemoveThingFromThingGroup ......................................................................................... 587
ReplaceTopicRule ............................................................................................................ 590
SearchIndex ................................................................................................................... 599
SetDefaultAuthorizer ....................................................................................................... 603
SetDefaultPolicyVersion ................................................................................................... 606
SetLoggingOptions ......................................................................................................... 608
SetV2LoggingLevel ......................................................................................................... 610
SetV2LoggingOptions ..................................................................................................... 612
StartAuditMitigationActionsTask ....................................................................................... 614
StartDetectMitigationActionsTask ..................................................................................... 617
StartOnDemandAuditTask ................................................................................................ 620
StartThingRegistrationTask .............................................................................................. 622

vi
 AWS IoT API Reference

StopThingRegistrationTask ............................................................................................... 625

TagResource ................................................................................................................... 627
TestAuthorization ........................................................................................................... 629
TestInvokeAuthorizer ....................................................................................................... 633
TransferCertificate .......................................................................................................... 637
UntagResource ............................................................................................................... 640
UpdateAccountAuditConfiguration .................................................................................... 642
UpdateAuditSuppression .................................................................................................. 645
UpdateAuthorizer ........................................................................................................... 648
UpdateBillingGroup ......................................................................................................... 652
UpdateCACertificate ........................................................................................................ 655
UpdateCertificate ............................................................................................................ 658
UpdateCustomMetric ....................................................................................................... 661
UpdateDimension ........................................................................................................... 664
UpdateDomainConfiguration ............................................................................................ 667
UpdateDynamicThingGroup ............................................................................................. 670
UpdateEventConfigurations .............................................................................................. 673
UpdateFleetMetric .......................................................................................................... 675
UpdateIndexingConfiguration ........................................................................................... 679
UpdateJob ..................................................................................................................... 682
UpdateMitigationAction ................................................................................................... 686
UpdatePackage .............................................................................................................. 689
UpdatePackageConfiguration ........................................................................................... 692
UpdatePackageVersion .................................................................................................... 694
UpdateProvisioningTemplate ............................................................................................ 697
UpdateRoleAlias ............................................................................................................. 700
UpdateScheduledAudit .................................................................................................... 703
UpdateSecurityProfile ...................................................................................................... 706
UpdateStream ................................................................................................................ 713
UpdateThing .................................................................................................................. 716
UpdateThingGroup ......................................................................................................... 719
UpdateThingGroupsForThing ............................................................................................ 722
UpdateTopicRuleDestination ............................................................................................ 725
ValidateSecurityProfileBehaviors ....................................................................................... 728
AWS IoT data ......................................................................................................................... 730
DeleteThingShadow ........................................................................................................ 731
GetRetainedMessage ....................................................................................................... 734
GetThingShadow ............................................................................................................ 737
ListNamedShadowsForThing ............................................................................................ 740
ListRetainedMessages ...................................................................................................... 743
Publish .......................................................................................................................... 746
UpdateThingShadow ....................................................................................................... 749
AWS IoT jobs data .................................................................................................................. 751
DescribeJobExecution ...................................................................................................... 752
GetPendingJobExecutions ................................................................................................ 755
StartNextPendingJobExecution ......................................................................................... 758
UpdateJobExecution ....................................................................................................... 761
AWS IoT Core Device Advisor ................................................................................................... 764
CreateSuiteDefinition ...................................................................................................... 766
DeleteSuiteDefinition ...................................................................................................... 769
GetEndpoint ................................................................................................................... 771
GetSuiteDefinition .......................................................................................................... 773
GetSuiteRun ................................................................................................................... 776
GetSuiteRunReport ......................................................................................................... 780
ListSuiteDefinitions ......................................................................................................... 782
ListSuiteRuns ................................................................................................................. 784
ListTagsForResource ........................................................................................................ 787

vii
 AWS IoT API Reference

StartSuiteRun ................................................................................................................. 789

StopSuiteRun ................................................................................................................. 792
TagResource ................................................................................................................... 794
UntagResource ............................................................................................................... 796
UpdateSuiteDefinition ..................................................................................................... 798
AWS IoT Fleet Hub ................................................................................................................. 800
CreateApplication ........................................................................................................... 801
DeleteApplication ........................................................................................................... 804
DescribeApplication ........................................................................................................ 806
ListApplications .............................................................................................................. 810
ListTagsForResource ........................................................................................................ 812
TagResource ................................................................................................................... 814
UntagResource ............................................................................................................... 816
UpdateApplication .......................................................................................................... 818
AWS IoT Secure Tunneling ....................................................................................................... 820
CloseTunnel ................................................................................................................... 821
DescribeTunnel ............................................................................................................... 823
ListTagsForResource ........................................................................................................ 825
ListTunnels .................................................................................................................... 827
OpenTunnel ................................................................................................................... 829
RotateTunnelAccessToken ................................................................................................ 832
TagResource ................................................................................................................... 835
UntagResource ............................................................................................................... 837
Data Types .................................................................................................................................... 839
AWS IoT ................................................................................................................................ 844
AbortConfig ................................................................................................................... 850
AbortCriteria .................................................................................................................. 851
Action ........................................................................................................................... 853
ActiveViolation ............................................................................................................... 857
AddThingsToThingGroupParams ....................................................................................... 859
AggregationType ............................................................................................................ 860
AlertTarget .................................................................................................................... 861
Allowed ......................................................................................................................... 862
AssetPropertyTimestamp ................................................................................................. 863
AssetPropertyValue ......................................................................................................... 864
AssetPropertyVariant ....................................................................................................... 865
AttributePayload ............................................................................................................ 866
AuditCheckConfiguration ................................................................................................. 867
AuditCheckDetails ........................................................................................................... 868
AuditFinding .................................................................................................................. 870
AuditMitigationActionExecutionMetadata ........................................................................... 872
AuditMitigationActionsTaskMetadata ................................................................................. 874
AuditMitigationActionsTaskTarget ..................................................................................... 875
AuditNotificationTarget ................................................................................................... 876
AuditSuppression ............................................................................................................ 877
AuditTaskMetadata ......................................................................................................... 879
AuthInfo ........................................................................................................................ 880
AuthorizerConfig ............................................................................................................ 881
AuthorizerDescription ...................................................................................................... 882
AuthorizerSummary ........................................................................................................ 884
AuthResult ..................................................................................................................... 885
AwsJobAbortConfig ......................................................................................................... 886
AwsJobAbortCriteria ........................................................................................................ 887
AwsJobExecutionsRolloutConfig ........................................................................................ 889
AwsJobExponentialRolloutRate ......................................................................................... 890
AwsJobPresignedUrlConfig ............................................................................................... 891
AwsJobRateIncreaseCriteria .............................................................................................. 892

viii
 AWS IoT API Reference

AwsJobTimeoutConfig ..................................................................................................... 893

Behavior ........................................................................................................................ 894
BehaviorCriteria .............................................................................................................. 896
BehaviorModelTrainingSummary ....................................................................................... 898
BillingGroupMetadata ...................................................................................................... 900
BillingGroupProperties .................................................................................................... 901
Bucket ........................................................................................................................... 902
BucketsAggregationType .................................................................................................. 903
CACertificate .................................................................................................................. 904
CACertificateDescription .................................................................................................. 905
Certificate ...................................................................................................................... 908
CertificateDescription ...................................................................................................... 910
CertificateValidity ........................................................................................................... 913
CloudwatchAlarmAction .................................................................................................. 914
CloudwatchLogsAction .................................................................................................... 915
CloudwatchMetricAction .................................................................................................. 916
CodeSigning ................................................................................................................... 918
CodeSigningCertificateChain ............................................................................................ 919
CodeSigningSignature ..................................................................................................... 920
Configuration ................................................................................................................. 921
CustomCodeSigning ........................................................................................................ 922
Denied .......................................................................................................................... 923
Destination .................................................................................................................... 924
DetectMitigationActionExecution ...................................................................................... 925
DetectMitigationActionsTaskStatistics ................................................................................ 927
DetectMitigationActionsTaskSummary ............................................................................... 928
DetectMitigationActionsTaskTarget ................................................................................... 930
DocumentParameter ....................................................................................................... 931
DomainConfigurationSummary ......................................................................................... 933
DynamoDBAction ............................................................................................................ 934
DynamoDBv2Action ........................................................................................................ 936
EffectivePolicy ................................................................................................................ 937
ElasticsearchAction ......................................................................................................... 938
EnableIoTLoggingParams ................................................................................................. 940
ErrorInfo ........................................................................................................................ 941
ExplicitDeny ................................................................................................................... 942
ExponentialRolloutRate ................................................................................................... 943
Field ............................................................................................................................. 944
FileLocation ................................................................................................................... 945
FirehoseAction ................................................................................................................ 946
FleetMetricNameAndArn .................................................................................................. 947
GeoLocationTarget .......................................................................................................... 948
GroupNameAndArn ......................................................................................................... 949
HttpAction ..................................................................................................................... 950
HttpActionHeader ........................................................................................................... 952
HttpAuthorization ........................................................................................................... 953
HttpContext ................................................................................................................... 954
HttpUrlDestinationConfiguration ...................................................................................... 955
HttpUrlDestinationProperties ........................................................................................... 956
HttpUrlDestinationSummary ............................................................................................ 957
ImplicitDeny ................................................................................................................... 958
IndexingFilter ................................................................................................................. 959
IotAnalyticsAction ........................................................................................................... 960
IotEventsAction .............................................................................................................. 961
IotSiteWiseAction ........................................................................................................... 963
IssuerCertificateIdentifier ................................................................................................. 964
Job ............................................................................................................................... 965

ix
 AWS IoT API Reference

JobExecution .................................................................................................................. 970

JobExecutionsRetryConfig ................................................................................................ 972
JobExecutionsRolloutConfig ............................................................................................. 973
JobExecutionStatusDetails ............................................................................................... 974
JobExecutionSummary .................................................................................................... 975
JobExecutionSummaryForJob ........................................................................................... 977
JobExecutionSummaryForThing ........................................................................................ 978
JobProcessDetails ........................................................................................................... 979
JobSummary .................................................................................................................. 981
JobTemplateSummary ..................................................................................................... 983
KafkaAction ................................................................................................................... 985
KafkaActionHeader ......................................................................................................... 987
KeyPair .......................................................................................................................... 988
KinesisAction .................................................................................................................. 989
LambdaAction ................................................................................................................ 990
LocationAction ............................................................................................................... 991
LocationTimestamp ......................................................................................................... 993
LoggingOptionsPayload ................................................................................................... 994
LogTarget ...................................................................................................................... 995
LogTargetConfiguration ................................................................................................... 996
MachineLearningDetectionConfig ...................................................................................... 997
MaintenanceWindow ....................................................................................................... 998
ManagedJobTemplateSummary ........................................................................................ 999
MetricDatum ................................................................................................................ 1001
MetricDimension ........................................................................................................... 1002
MetricsExportConfig ...................................................................................................... 1003
MetricToRetain ............................................................................................................. 1004
MetricValue .................................................................................................................. 1005
MitigationAction ........................................................................................................... 1007
MitigationActionIdentifier .............................................................................................. 1008
MitigationActionParams ................................................................................................. 1009
MqttContext ................................................................................................................. 1011
MqttHeaders ................................................................................................................ 1012
NonCompliantResource .................................................................................................. 1014
OpenSearchAction ........................................................................................................ 1015
OTAUpdateFile ............................................................................................................. 1016
OTAUpdateInfo ............................................................................................................. 1018
OTAUpdateSummary ..................................................................................................... 1021
OutgoingCertificate ....................................................................................................... 1022
PackageSummary ......................................................................................................... 1024
PackageVersionSummary ............................................................................................... 1025
PercentPair .................................................................................................................. 1027
Policy .......................................................................................................................... 1028
PolicyVersion ................................................................................................................ 1029
PolicyVersionIdentifier ................................................................................................... 1030
PresignedUrlConfig ....................................................................................................... 1031
ProvisioningHook .......................................................................................................... 1032
ProvisioningTemplateSummary ....................................................................................... 1033
ProvisioningTemplateVersionSummary ............................................................................ 1035
PublishFindingToSnsParams ........................................................................................... 1036
PutAssetPropertyValueEntry ........................................................................................... 1037
PutItemInput ................................................................................................................ 1039
RateIncreaseCriteria ....................................................................................................... 1040
RegistrationConfig ........................................................................................................ 1041
RelatedResource ........................................................................................................... 1042
ReplaceDefaultPolicyVersionParams ................................................................................ 1043
RepublishAction ............................................................................................................ 1044

x
 AWS IoT API Reference

ResourceIdentifier ......................................................................................................... 1045

RetryCriteria ................................................................................................................. 1047
RoleAliasDescription ...................................................................................................... 1048
S3Action ...................................................................................................................... 1050
S3Destination ............................................................................................................... 1051
S3Location ................................................................................................................... 1052
SalesforceAction ........................................................................................................... 1053
ScheduledAuditMetadata ............................................................................................... 1054
ScheduledJobRollout ..................................................................................................... 1056
SchedulingConfig .......................................................................................................... 1057
SecurityProfileIdentifier ................................................................................................. 1059
SecurityProfileTarget ..................................................................................................... 1060
SecurityProfileTargetMapping ......................................................................................... 1061
ServerCertificateSummary .............................................................................................. 1062
SigningProfileParameter ................................................................................................ 1063
SigV4Authorization ....................................................................................................... 1064
SnsAction ..................................................................................................................... 1065
SqsAction ..................................................................................................................... 1066
StartSigningJobParameter ............................................................................................. 1067
StatisticalThreshold ....................................................................................................... 1068
Statistics ...................................................................................................................... 1069
StepFunctionsAction ...................................................................................................... 1071
Stream ........................................................................................................................ 1072
StreamFile ................................................................................................................... 1073
StreamInfo ................................................................................................................... 1074
StreamSummary ........................................................................................................... 1076
Tag ............................................................................................................................. 1077
TaskStatistics ................................................................................................................ 1078
TaskStatisticsForAuditCheck ........................................................................................... 1080
TermsAggregation ......................................................................................................... 1081
ThingAttribute .............................................................................................................. 1082
ThingConnectivity ......................................................................................................... 1084
ThingDocument ............................................................................................................ 1085
ThingGroupDocument ................................................................................................... 1087
ThingGroupIndexingConfiguration ................................................................................... 1089
ThingGroupMetadata ..................................................................................................... 1090
ThingGroupProperties ................................................................................................... 1091
ThingIndexingConfiguration ........................................................................................... 1092
ThingTypeDefinition ...................................................................................................... 1094
ThingTypeMetadata ....................................................................................................... 1095
ThingTypeProperties ..................................................................................................... 1096
TimeoutConfig .............................................................................................................. 1097
TimestreamAction ......................................................................................................... 1098
TimestreamDimension ................................................................................................... 1100
TimestreamTimestamp .................................................................................................. 1101
TlsConfig ..................................................................................................................... 1102
TlsContext ................................................................................................................... 1103
TopicRule ..................................................................................................................... 1104
TopicRuleDestination ..................................................................................................... 1106
TopicRuleDestinationConfiguration .................................................................................. 1108
TopicRuleDestinationSummary ....................................................................................... 1109
TopicRuleListItem .......................................................................................................... 1111
TopicRulePayload .......................................................................................................... 1112
TransferData ................................................................................................................ 1114
UpdateCACertificateParams ............................................................................................ 1116
UpdateDeviceCertificateParams ...................................................................................... 1117
UserProperty ................................................................................................................ 1118

xi
 AWS IoT API Reference

ValidationError ............................................................................................................. 1119

VersionUpdateByJobsConfig ........................................................................................... 1120
ViolationEvent .............................................................................................................. 1121
ViolationEventAdditionalInfo .......................................................................................... 1123
ViolationEventOccurrenceRange ...................................................................................... 1124
VpcDestinationConfiguration .......................................................................................... 1125
VpcDestinationProperties ............................................................................................... 1126
VpcDestinationSummary ................................................................................................ 1127
AWS IoT data ....................................................................................................................... 1127
RetainedMessageSummary ............................................................................................. 1128
AWS IoT jobs data ................................................................................................................ 1128
JobExecution ................................................................................................................ 1130
JobExecutionState ......................................................................................................... 1133
JobExecutionSummary .................................................................................................. 1134
AWS IoT Core Device Advisor ................................................................................................. 1135
DeviceUnderTest ........................................................................................................... 1136
GroupResult ................................................................................................................. 1137
SuiteDefinitionConfiguration .......................................................................................... 1138
SuiteDefinitionInformation ............................................................................................. 1140
SuiteRunConfiguration ................................................................................................... 1142
SuiteRunInformation ..................................................................................................... 1143
TestCaseRun ................................................................................................................. 1145
TestCaseScenario .......................................................................................................... 1147
TestResult .................................................................................................................... 1149
AWS IoT Fleet Hub ............................................................................................................... 1149
ApplicationSummary ..................................................................................................... 1150
AWS IoT Secure Tunneling ..................................................................................................... 1151
ConnectionState ........................................................................................................... 1152
DestinationConfig ......................................................................................................... 1153
Tag ............................................................................................................................. 1154
TimeoutConfig .............................................................................................................. 1155
Tunnel ......................................................................................................................... 1156
TunnelSummary ........................................................................................................... 1158
Common Parameters ..................................................................................................................... 1160

xii
 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 Tunneling 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. 16)

• AddThingToBillingGroup (p. 18)
• AddThingToThingGroup (p. 21)
• AssociateTargetsWithJob (p. 24)
• AttachPolicy (p. 27)
• AttachPrincipalPolicy (p. 29)
• AttachSecurityProfile (p. 31)
• AttachThingPrincipal (p. 33)
• CancelAuditMitigationActionsTask (p. 35)
• CancelAuditTask (p. 37)
• CancelCertificateTransfer (p. 39)
• CancelDetectMitigationActionsTask (p. 41)
• CancelJob (p. 43)
• CancelJobExecution (p. 46)
• ClearDefaultAuthorizer (p. 49)
• ConfirmTopicRuleDestination (p. 51)
• CreateAuditSuppression (p. 53)
• CreateAuthorizer (p. 56)
• CreateBillingGroup (p. 60)
• CreateCertificateFromCsr (p. 63)
• CreateCustomMetric (p. 66)
• CreateDimension (p. 69)
• CreateDomainConfiguration (p. 72)
• CreateDynamicThingGroup (p. 76)
• CreateFleetMetric (p. 80)
• CreateJob (p. 85)
• CreateJobTemplate (p. 92)
• CreateKeysAndCertificate (p. 97)
• CreateMitigationAction (p. 100)
• CreateOTAUpdate (p. 103)
• CreatePackage (p. 109)
• CreatePackageVersion (p. 112)
• CreatePolicy (p. 116)
• CreatePolicyVersion (p. 119)
• CreateProvisioningClaim (p. 122)
• CreateProvisioningTemplate (p. 125)
• CreateProvisioningTemplateVersion (p. 129)
• CreateRoleAlias (p. 132)
• CreateScheduledAudit (p. 135)
• CreateSecurityProfile (p. 138)

3
 AWS IoT API Reference

• CreateStream (p. 142)

• CreateThing (p. 146)
• CreateThingGroup (p. 149)
• CreateThingType (p. 152)
• CreateTopicRule (p. 155)
• CreateTopicRuleDestination (p. 164)
• DeleteAccountAuditConfiguration (p. 167)
• DeleteAuditSuppression (p. 169)
• DeleteAuthorizer (p. 171)
• DeleteBillingGroup (p. 173)
• DeleteCACertificate (p. 175)
• DeleteCertificate (p. 177)
• DeleteCustomMetric (p. 179)
• DeleteDimension (p. 181)
• DeleteDomainConfiguration (p. 183)
• DeleteDynamicThingGroup (p. 185)
• DeleteFleetMetric (p. 187)
• DeleteJob (p. 189)
• DeleteJobExecution (p. 192)
• DeleteJobTemplate (p. 195)
• DeleteMitigationAction (p. 197)
• DeleteOTAUpdate (p. 199)
• DeletePackage (p. 201)
• DeletePackageVersion (p. 203)
• DeletePolicy (p. 205)
• DeletePolicyVersion (p. 207)
• DeleteProvisioningTemplate (p. 209)
• DeleteProvisioningTemplateVersion (p. 211)
• DeleteRegistrationCode (p. 213)
• DeleteRoleAlias (p. 215)
• DeleteScheduledAudit (p. 217)
• DeleteSecurityProfile (p. 219)
• DeleteStream (p. 221)
• DeleteThing (p. 223)
• DeleteThingGroup (p. 225)
• DeleteThingType (p. 227)
• DeleteTopicRule (p. 229)
• DeleteTopicRuleDestination (p. 231)
• DeleteV2LoggingLevel (p. 233)
• DeprecateThingType (p. 235)
• DescribeAccountAuditConfiguration (p. 237)
• DescribeAuditFinding (p. 239)
• DescribeAuditMitigationActionsTask (p. 242)
• DescribeAuditSuppression (p. 246)
• DescribeAuditTask (p. 249)
• DescribeAuthorizer (p. 252)

4
 AWS IoT API Reference

• DescribeBillingGroup (p. 254)

• DescribeCACertificate (p. 257)
• DescribeCertificate (p. 260)
• DescribeCustomMetric (p. 263)
• DescribeDefaultAuthorizer (p. 266)
• DescribeDetectMitigationActionsTask (p. 268)
• DescribeDimension (p. 271)
• DescribeDomainConfiguration (p. 274)
• DescribeEndpoint (p. 278)
• DescribeEventConfigurations (p. 280)
• DescribeFleetMetric (p. 282)
• DescribeIndex (p. 286)
• DescribeJob (p. 289)
• DescribeJobExecution (p. 293)
• DescribeJobTemplate (p. 296)
• DescribeManagedJobTemplate (p. 300)
• DescribeMitigationAction (p. 303)
• DescribeProvisioningTemplate (p. 306)
• DescribeProvisioningTemplateVersion (p. 310)
• DescribeRoleAlias (p. 313)
• DescribeScheduledAudit (p. 315)
• DescribeSecurityProfile (p. 318)
• DescribeStream (p. 322)
• DescribeThing (p. 325)
• DescribeThingGroup (p. 328)
• DescribeThingRegistrationTask (p. 332)
• DescribeThingType (p. 336)
• DetachPolicy (p. 339)
• DetachPrincipalPolicy (p. 341)
• DetachSecurityProfile (p. 343)
• DetachThingPrincipal (p. 345)
• DisableTopicRule (p. 347)
• EnableTopicRule (p. 349)
• GetBehaviorModelTrainingSummaries (p. 351)
• GetBucketsAggregation (p. 353)
• GetCardinality (p. 357)
• GetEffectivePolicies (p. 360)
• GetIndexingConfiguration (p. 363)
• GetJobDocument (p. 366)
• GetLoggingOptions (p. 368)
• GetOTAUpdate (p. 370)
• GetPackage (p. 374)
• GetPackageConfiguration (p. 377)
• GetPackageVersion (p. 379)
• GetPercentiles (p. 383)
• GetPolicy (p. 386)

5
 AWS IoT API Reference

• GetPolicyVersion (p. 389)

• GetRegistrationCode (p. 392)
• GetStatistics (p. 394)
• GetTopicRule (p. 397)
• GetTopicRuleDestination (p. 406)
• GetV2LoggingOptions (p. 408)
• ListActiveViolations (p. 410)
• ListAttachedPolicies (p. 413)
• ListAuditFindings (p. 416)
• ListAuditMitigationActionsExecutions (p. 420)
• ListAuditMitigationActionsTasks (p. 423)
• ListAuditSuppressions (p. 426)
• ListAuditTasks (p. 429)
• ListAuthorizers (p. 432)
• ListBillingGroups (p. 435)
• ListCACertificates (p. 437)
• ListCertificates (p. 440)
• ListCertificatesByCA (p. 443)
• ListCustomMetrics (p. 446)
• ListDetectMitigationActionsExecutions (p. 448)
• ListDetectMitigationActionsTasks (p. 451)
• ListDimensions (p. 454)
• ListDomainConfigurations (p. 456)
• ListFleetMetrics (p. 459)
• ListIndices (p. 461)
• ListJobExecutionsForJob (p. 463)
• ListJobExecutionsForThing (p. 466)
• ListJobs (p. 469)
• ListJobTemplates (p. 472)
• ListManagedJobTemplates (p. 474)
• ListMetricValues (p. 476)
• ListMitigationActions (p. 479)
• ListOTAUpdates (p. 481)
• ListOutgoingCertificates (p. 484)
• ListPackages (p. 487)
• ListPackageVersions (p. 489)
• ListPolicies (p. 491)
• ListPolicyPrincipals (p. 494)
• ListPolicyVersions (p. 497)
• ListPrincipalPolicies (p. 499)
• ListPrincipalThings (p. 502)
• ListProvisioningTemplates (p. 505)
• ListProvisioningTemplateVersions (p. 507)
• ListRelatedResourcesForAuditFinding (p. 510)
• ListRoleAliases (p. 513)
• ListScheduledAudits (p. 516)

6
 AWS IoT API Reference

• ListSecurityProfiles (p. 518)

• ListSecurityProfilesForTarget (p. 521)
• ListStreams (p. 524)
• ListTagsForResource (p. 526)
• ListTargetsForPolicy (p. 528)
• ListTargetsForSecurityProfile (p. 531)
• ListThingGroups (p. 533)
• ListThingGroupsForThing (p. 536)
• ListThingPrincipals (p. 538)
• ListThingRegistrationTaskReports (p. 541)
• ListThingRegistrationTasks (p. 544)
• ListThings (p. 546)
• ListThingsInBillingGroup (p. 549)
• ListThingsInThingGroup (p. 551)
• ListThingTypes (p. 553)
• ListTopicRuleDestinations (p. 556)
• ListTopicRules (p. 558)
• ListV2LoggingLevels (p. 560)
• ListViolationEvents (p. 562)
• PutVerificationStateOnViolation (p. 566)
• RegisterCACertificate (p. 568)
• RegisterCertificate (p. 572)
• RegisterCertificateWithoutCA (p. 575)
• RegisterThing (p. 578)
• RejectCertificateTransfer (p. 581)
• RemoveThingFromBillingGroup (p. 584)
• RemoveThingFromThingGroup (p. 587)
• ReplaceTopicRule (p. 590)
• SearchIndex (p. 599)
• SetDefaultAuthorizer (p. 603)
• SetDefaultPolicyVersion (p. 606)
• SetLoggingOptions (p. 608)
• SetV2LoggingLevel (p. 610)
• SetV2LoggingOptions (p. 612)
• StartAuditMitigationActionsTask (p. 614)
• StartDetectMitigationActionsTask (p. 617)
• StartOnDemandAuditTask (p. 620)
• StartThingRegistrationTask (p. 622)
• StopThingRegistrationTask (p. 625)
• TagResource (p. 627)
• TestAuthorization (p. 629)
• TestInvokeAuthorizer (p. 633)
• TransferCertificate (p. 637)
• UntagResource (p. 640)
• UpdateAccountAuditConfiguration (p. 642)
• UpdateAuditSuppression (p. 645)

7
 AWS IoT API Reference

• UpdateAuthorizer (p. 648)

• UpdateBillingGroup (p. 652)
• UpdateCACertificate (p. 655)
• UpdateCertificate (p. 658)
• UpdateCustomMetric (p. 661)
• UpdateDimension (p. 664)
• UpdateDomainConfiguration (p. 667)
• UpdateDynamicThingGroup (p. 670)
• UpdateEventConfigurations (p. 673)
• UpdateFleetMetric (p. 675)
• UpdateIndexingConfiguration (p. 679)
• UpdateJob (p. 682)
• UpdateMitigationAction (p. 686)
• UpdatePackage (p. 689)
• UpdatePackageConfiguration (p. 692)
• UpdatePackageVersion (p. 694)
• UpdateProvisioningTemplate (p. 697)
• UpdateRoleAlias (p. 700)
• UpdateScheduledAudit (p. 703)
• UpdateSecurityProfile (p. 706)
• UpdateStream (p. 713)
• UpdateThing (p. 716)
• UpdateThingGroup (p. 719)
• UpdateThingGroupsForThing (p. 722)
• UpdateTopicRuleDestination (p. 725)
• ValidateSecurityProfileBehaviors (p. 728)

The following actions are supported by AWS IoT data:

• DeleteThingShadow (p. 731)

• GetRetainedMessage (p. 734)
• GetThingShadow (p. 737)
• ListNamedShadowsForThing (p. 740)
• ListRetainedMessages (p. 743)
• Publish (p. 746)
• UpdateThingShadow (p. 749)

The following actions are supported by AWS IoT jobs data:

• DescribeJobExecution (p. 752)

• GetPendingJobExecutions (p. 755)
• StartNextPendingJobExecution (p. 758)
• UpdateJobExecution (p. 761)

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

• CreateSuiteDefinition (p. 766)

8
 AWS IoT API Reference
AWS IoT

• DeleteSuiteDefinition (p. 769)

• GetEndpoint (p. 771)
• GetSuiteDefinition (p. 773)
• GetSuiteRun (p. 776)
• GetSuiteRunReport (p. 780)
• ListSuiteDefinitions (p. 782)
• ListSuiteRuns (p. 784)
• ListTagsForResource (p. 787)
• StartSuiteRun (p. 789)
• StopSuiteRun (p. 792)
• TagResource (p. 794)
• UntagResource (p. 796)
• UpdateSuiteDefinition (p. 798)

The following actions are supported by AWS IoT Fleet Hub:

• CreateApplication (p. 801)

• DeleteApplication (p. 804)
• DescribeApplication (p. 806)
• ListApplications (p. 810)
• ListTagsForResource (p. 812)
• TagResource (p. 814)
• UntagResource (p. 816)
• UpdateApplication (p. 818)

The following actions are supported by AWS IoT Secure Tunneling:

• CloseTunnel (p. 821)

• DescribeTunnel (p. 823)
• ListTagsForResource (p. 825)
• ListTunnels (p. 827)
• OpenTunnel (p. 829)
• RotateTunnelAccessToken (p. 832)
• TagResource (p. 835)
• UntagResource (p. 837)

AWS IoT
The following actions are supported by AWS IoT:

• AcceptCertificateTransfer (p. 16)

• AddThingToBillingGroup (p. 18)
• AddThingToThingGroup (p. 21)
• AssociateTargetsWithJob (p. 24)
• AttachPolicy (p. 27)
• AttachPrincipalPolicy (p. 29)

9
 AWS IoT API Reference
AWS IoT

• AttachSecurityProfile (p. 31)

• AttachThingPrincipal (p. 33)
• CancelAuditMitigationActionsTask (p. 35)
• CancelAuditTask (p. 37)
• CancelCertificateTransfer (p. 39)
• CancelDetectMitigationActionsTask (p. 41)
• CancelJob (p. 43)
• CancelJobExecution (p. 46)
• ClearDefaultAuthorizer (p. 49)
• ConfirmTopicRuleDestination (p. 51)
• CreateAuditSuppression (p. 53)
• CreateAuthorizer (p. 56)
• CreateBillingGroup (p. 60)
• CreateCertificateFromCsr (p. 63)
• CreateCustomMetric (p. 66)
• CreateDimension (p. 69)
• CreateDomainConfiguration (p. 72)
• CreateDynamicThingGroup (p. 76)
• CreateFleetMetric (p. 80)
• CreateJob (p. 85)
• CreateJobTemplate (p. 92)
• CreateKeysAndCertificate (p. 97)
• CreateMitigationAction (p. 100)
• CreateOTAUpdate (p. 103)
• CreatePackage (p. 109)
• CreatePackageVersion (p. 112)
• CreatePolicy (p. 116)
• CreatePolicyVersion (p. 119)
• CreateProvisioningClaim (p. 122)
• CreateProvisioningTemplate (p. 125)
• CreateProvisioningTemplateVersion (p. 129)
• CreateRoleAlias (p. 132)
• CreateScheduledAudit (p. 135)
• CreateSecurityProfile (p. 138)
• CreateStream (p. 142)
• CreateThing (p. 146)
• CreateThingGroup (p. 149)
• CreateThingType (p. 152)
• CreateTopicRule (p. 155)
• CreateTopicRuleDestination (p. 164)
• DeleteAccountAuditConfiguration (p. 167)
• DeleteAuditSuppression (p. 169)
• DeleteAuthorizer (p. 171)
• DeleteBillingGroup (p. 173)
• DeleteCACertificate (p. 175)
• DeleteCertificate (p. 177)

10
 AWS IoT API Reference
AWS IoT

• DeleteCustomMetric (p. 179)

• DeleteDimension (p. 181)
• DeleteDomainConfiguration (p. 183)
• DeleteDynamicThingGroup (p. 185)
• DeleteFleetMetric (p. 187)
• DeleteJob (p. 189)
• DeleteJobExecution (p. 192)
• DeleteJobTemplate (p. 195)
• DeleteMitigationAction (p. 197)
• DeleteOTAUpdate (p. 199)
• DeletePackage (p. 201)
• DeletePackageVersion (p. 203)
• DeletePolicy (p. 205)
• DeletePolicyVersion (p. 207)
• DeleteProvisioningTemplate (p. 209)
• DeleteProvisioningTemplateVersion (p. 211)
• DeleteRegistrationCode (p. 213)
• DeleteRoleAlias (p. 215)
• DeleteScheduledAudit (p. 217)
• DeleteSecurityProfile (p. 219)
• DeleteStream (p. 221)
• DeleteThing (p. 223)
• DeleteThingGroup (p. 225)
• DeleteThingType (p. 227)
• DeleteTopicRule (p. 229)
• DeleteTopicRuleDestination (p. 231)
• DeleteV2LoggingLevel (p. 233)
• DeprecateThingType (p. 235)
• DescribeAccountAuditConfiguration (p. 237)
• DescribeAuditFinding (p. 239)
• DescribeAuditMitigationActionsTask (p. 242)
• DescribeAuditSuppression (p. 246)
• DescribeAuditTask (p. 249)
• DescribeAuthorizer (p. 252)
• DescribeBillingGroup (p. 254)
• DescribeCACertificate (p. 257)
• DescribeCertificate (p. 260)
• DescribeCustomMetric (p. 263)
• DescribeDefaultAuthorizer (p. 266)
• DescribeDetectMitigationActionsTask (p. 268)
• DescribeDimension (p. 271)
• DescribeDomainConfiguration (p. 274)
• DescribeEndpoint (p. 278)
• DescribeEventConfigurations (p. 280)
• DescribeFleetMetric (p. 282)
• DescribeIndex (p. 286)

11
 AWS IoT API Reference
AWS IoT

• DescribeJob (p. 289)

• DescribeJobExecution (p. 293)
• DescribeJobTemplate (p. 296)
• DescribeManagedJobTemplate (p. 300)
• DescribeMitigationAction (p. 303)
• DescribeProvisioningTemplate (p. 306)
• DescribeProvisioningTemplateVersion (p. 310)
• DescribeRoleAlias (p. 313)
• DescribeScheduledAudit (p. 315)
• DescribeSecurityProfile (p. 318)
• DescribeStream (p. 322)
• DescribeThing (p. 325)
• DescribeThingGroup (p. 328)
• DescribeThingRegistrationTask (p. 332)
• DescribeThingType (p. 336)
• DetachPolicy (p. 339)
• DetachPrincipalPolicy (p. 341)
• DetachSecurityProfile (p. 343)
• DetachThingPrincipal (p. 345)
• DisableTopicRule (p. 347)
• EnableTopicRule (p. 349)
• GetBehaviorModelTrainingSummaries (p. 351)
• GetBucketsAggregation (p. 353)
• GetCardinality (p. 357)
• GetEffectivePolicies (p. 360)
• GetIndexingConfiguration (p. 363)
• GetJobDocument (p. 366)
• GetLoggingOptions (p. 368)
• GetOTAUpdate (p. 370)
• GetPackage (p. 374)
• GetPackageConfiguration (p. 377)
• GetPackageVersion (p. 379)
• GetPercentiles (p. 383)
• GetPolicy (p. 386)
• GetPolicyVersion (p. 389)
• GetRegistrationCode (p. 392)
• GetStatistics (p. 394)
• GetTopicRule (p. 397)
• GetTopicRuleDestination (p. 406)
• GetV2LoggingOptions (p. 408)
• ListActiveViolations (p. 410)
• ListAttachedPolicies (p. 413)
• ListAuditFindings (p. 416)
• ListAuditMitigationActionsExecutions (p. 420)
• ListAuditMitigationActionsTasks (p. 423)
• ListAuditSuppressions (p. 426)

12
 AWS IoT API Reference
AWS IoT

• ListAuditTasks (p. 429)

• ListAuthorizers (p. 432)
• ListBillingGroups (p. 435)
• ListCACertificates (p. 437)
• ListCertificates (p. 440)
• ListCertificatesByCA (p. 443)
• ListCustomMetrics (p. 446)
• ListDetectMitigationActionsExecutions (p. 448)
• ListDetectMitigationActionsTasks (p. 451)
• ListDimensions (p. 454)
• ListDomainConfigurations (p. 456)
• ListFleetMetrics (p. 459)
• ListIndices (p. 461)
• ListJobExecutionsForJob (p. 463)
• ListJobExecutionsForThing (p. 466)
• ListJobs (p. 469)
• ListJobTemplates (p. 472)
• ListManagedJobTemplates (p. 474)
• ListMetricValues (p. 476)
• ListMitigationActions (p. 479)
• ListOTAUpdates (p. 481)
• ListOutgoingCertificates (p. 484)
• ListPackages (p. 487)
• ListPackageVersions (p. 489)
• ListPolicies (p. 491)
• ListPolicyPrincipals (p. 494)
• ListPolicyVersions (p. 497)
• ListPrincipalPolicies (p. 499)
• ListPrincipalThings (p. 502)
• ListProvisioningTemplates (p. 505)
• ListProvisioningTemplateVersions (p. 507)
• ListRelatedResourcesForAuditFinding (p. 510)
• ListRoleAliases (p. 513)
• ListScheduledAudits (p. 516)
• ListSecurityProfiles (p. 518)
• ListSecurityProfilesForTarget (p. 521)
• ListStreams (p. 524)
• ListTagsForResource (p. 526)
• ListTargetsForPolicy (p. 528)
• ListTargetsForSecurityProfile (p. 531)
• ListThingGroups (p. 533)
• ListThingGroupsForThing (p. 536)
• ListThingPrincipals (p. 538)
• ListThingRegistrationTaskReports (p. 541)
• ListThingRegistrationTasks (p. 544)
• ListThings (p. 546)

13
 AWS IoT API Reference
AWS IoT

• ListThingsInBillingGroup (p. 549)

• ListThingsInThingGroup (p. 551)
• ListThingTypes (p. 553)
• ListTopicRuleDestinations (p. 556)
• ListTopicRules (p. 558)
• ListV2LoggingLevels (p. 560)
• ListViolationEvents (p. 562)
• PutVerificationStateOnViolation (p. 566)
• RegisterCACertificate (p. 568)
• RegisterCertificate (p. 572)
• RegisterCertificateWithoutCA (p. 575)
• RegisterThing (p. 578)
• RejectCertificateTransfer (p. 581)
• RemoveThingFromBillingGroup (p. 584)
• RemoveThingFromThingGroup (p. 587)
• ReplaceTopicRule (p. 590)
• SearchIndex (p. 599)
• SetDefaultAuthorizer (p. 603)
• SetDefaultPolicyVersion (p. 606)
• SetLoggingOptions (p. 608)
• SetV2LoggingLevel (p. 610)
• SetV2LoggingOptions (p. 612)
• StartAuditMitigationActionsTask (p. 614)
• StartDetectMitigationActionsTask (p. 617)
• StartOnDemandAuditTask (p. 620)
• StartThingRegistrationTask (p. 622)
• StopThingRegistrationTask (p. 625)
• TagResource (p. 627)
• TestAuthorization (p. 629)
• TestInvokeAuthorizer (p. 633)
• TransferCertificate (p. 637)
• UntagResource (p. 640)
• UpdateAccountAuditConfiguration (p. 642)
• UpdateAuditSuppression (p. 645)
• UpdateAuthorizer (p. 648)
• UpdateBillingGroup (p. 652)
• UpdateCACertificate (p. 655)
• UpdateCertificate (p. 658)
• UpdateCustomMetric (p. 661)
• UpdateDimension (p. 664)
• UpdateDomainConfiguration (p. 667)
• UpdateDynamicThingGroup (p. 670)
• UpdateEventConfigurations (p. 673)
• UpdateFleetMetric (p. 675)
• UpdateIndexingConfiguration (p. 679)
• UpdateJob (p. 682)

14
 AWS IoT API Reference
AWS IoT

• UpdateMitigationAction (p. 686)

• UpdatePackage (p. 689)
• UpdatePackageConfiguration (p. 692)
• UpdatePackageVersion (p. 694)
• UpdateProvisioningTemplate (p. 697)
• UpdateRoleAlias (p. 700)
• UpdateScheduledAudit (p. 703)
• UpdateSecurityProfile (p. 706)
• UpdateStream (p. 713)
• UpdateThing (p. 716)
• UpdateThingGroup (p. 719)
• UpdateThingGroupsForThing (p. 722)
• UpdateTopicRuleDestination (p. 725)
• ValidateSecurityProfileBehaviors (p. 728)

15
 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. 440) 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. 16)

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

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

16
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

17
 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. 18)

The ARN of the billing group.

Type: String

Required: No
billingGroupName (p. 18)

The name of the billing group.

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

Type: String

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

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

Required: No
thingArn (p. 18)

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

Type: String

Required: No
thingName (p. 18)

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

18
 AWS IoT API Reference
AddThingToBillingGroup

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

19
 AWS IoT API Reference
AddThingToBillingGroup

20
 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. 21)

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

The ARN of the thing to add to a group.

Type: String

Required: No
thingGroupArn (p. 21)

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

Type: String

Required: No
thingGroupName (p. 21)

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

Type: String

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

21
 AWS IoT API Reference
AddThingToThingGroup

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

Required: No
thingName (p. 21)

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

22
 AWS IoT API Reference
AddThingToThingGroup

• AWS SDK for Java V2

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

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

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

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.

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

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

comment (p. 24)

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

24
 AWS IoT API Reference
AssociateTargetsWithJob

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
targets (p. 24)

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

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

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

An ARN identifying the job.

Type: String
jobId (p. 25)

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_-]+

25
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

26
 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. 27)

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

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.

27
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

28
 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 and works as expected for backward compatibility, but we won't add
enhancements. Use AttachPolicy (p. 27) 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. 29)

The policy name.

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

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

Required: Yes
principal (p. 29)

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

29
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

30
 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. 31)

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

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.

31
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

32
 AWS IoT API Reference
AttachThingPrincipal

AttachThingPrincipal
Service: AWS IoT

Attaches the specified principal to the specified thing. A principal can be X.509 certificates, 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. 33)

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

Required: Yes
thingName (p. 33)

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.

33
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

34
 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. 35)

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.

35
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

36
 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. 37)

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.

37
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

38
 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. 581) 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. 39)

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.

39
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

40
 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. 41)

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

41
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

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

(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. 43)

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

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

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

43
 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. 44)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

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

The job ARN.

Type: String
jobId (p. 44)

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

44
 AWS IoT API Reference
CancelJob

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

45
 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. 46)

(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. 46)

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

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

(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

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

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

47
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

48
 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

49
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

50
 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. 51)

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.

51
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

52
 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 53)

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

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.

53
 AWS IoT API Reference
CreateAuditSuppression

Type: String

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

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

Required: Yes
description (p. 53)

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

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

Required: No
expirationDate (p. 53)

The epoch timestamp in seconds at which this suppression expires.

Type: Timestamp

Required: No
resourceIdentifier (p. 53)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 1045) object

Required: Yes
suppressIndefinitely (p. 53)

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.

54
 AWS IoT API Reference
CreateAuditSuppression

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

55
 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",
"enableCachingForHttp": boolean,
"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. 56)

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

The ARN of the authorizer's Lambda function.

Type: String

Length Constraints: Maximum length of 2048.

Pattern: [\s\S]*

Required: Yes

56
 AWS IoT API Reference
CreateAuthorizer

enableCachingForHttp (p. 56)

When true, the result from the authorizer’s Lambda function is cached for clients that use
persistent HTTP connections. The results are cached for the time specified by the Lambda function
in refreshAfterInSeconds. This value does not affect authorization of clients that use MQTT
connections.

The default value is false.

Type: Boolean

Required: No
signingDisabled (p. 56)

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

Type: Boolean

Required: No
status (p. 56)

The status of the create authorizer request.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
tags (p. 56)

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. 1077) objects

Required: No
tokenKeyName (p. 56)

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

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:_-]+

57
 AWS IoT API Reference
CreateAuthorizer

Value Length Constraints: Maximum length of 5120.

Value Pattern: [\s\S]*

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

The authorizer ARN.

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 58)

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

58
 AWS IoT API Reference
CreateAuthorizer

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

59
 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. 60)

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

The properties of the billing group.

Type: BillingGroupProperties (p. 901) object

Required: No
tags (p. 60)

Metadata which can be used to manage the billing group.

Type: Array of Tag (p. 1077) objects

Required: No

60
 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. 61)

The ARN of the billing group.

Type: String
billingGroupId (p. 61)

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

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

61
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

62
 AWS IoT API Reference
CreateCertificateFromCsr

CreateCertificateFromCsr
Service: AWS IoT

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

Requires permission to access the CreateCertificateFromCsr action.

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, NIST P-384, or NIST P-521 curves. For supported certificates,
consult Certificate signing algorithms supported by AWS IoT.
Note
Reusing the same certificate signing request (CSR) results in a distinct certificate.

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. In the following commands, we assume that 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.

You can also run the aws iot create-certificate-from-csr part of the command 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. 63)

Specifies whether the certificate is active.

63
 AWS IoT API Reference
CreateCertificateFromCsr

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

certificateSigningRequest (p. 63)

The certificate signing request (CSR).

Type: String

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

Pattern: [\s\S]*

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

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

Type: String
certificateId (p. 64)

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

The certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*

64
 AWS IoT API Reference
CreateCertificateFromCsr

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

65
 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. 66)

The name of the custom metric. This will be used in the metric report submitted from the device/
thing. The name can't begin with aws:. You can't change the name after you define 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.

clientRequestToken (p. 66)

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

66
 AWS IoT API Reference
CreateCustomMetric

displayName (p. 66)

The friendly name in the console for the custom metric. This name doesn't have to be unique. Don't
use this name as the metric identifier in the device metric report. You can update the friendly name
after you define it.

Type: String

Length Constraints: Maximum length of 128.

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

Required: No
metricType (p. 66)

The type of the custom metric.

Important
The type number only takes a single metric value as an input, but when you submit the
metrics value in the DeviceMetrics report, you must pass it as an array with a single value.

Type: String

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

Required: Yes
tags (p. 66)

Metadata that can be used to manage the custom metric.

Type: Array of Tag (p. 1077) 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. 67)

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

Type: String
metricName (p. 67)

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

67
 AWS IoT API Reference
CreateCustomMetric

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

68
 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. 69)

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

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

69
 AWS IoT API Reference
CreateDimension

stringValues (p. 69)

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

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

Required: Yes
tags (p. 69)

Metadata that can be used to manage the dimension.

Type: Array of Tag (p. 1077) objects

Required: No
type (p. 69)

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

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

Type: String
name (p. 70)

A unique identifier for the dimension.

Type: String

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

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

70
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

71
 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"
}
],
"tlsConfig": {
"securityPolicy": "string"
},
"validationCertificateArn": "string"
}

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 72)

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

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 881) object

Required: No

72
 AWS IoT API Reference
CreateDomainConfiguration

domainName (p. 72)

The name of the domain.

Type: String

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

Pattern: [\s\S]*

Required: No
serverCertificateArns (p. 72)

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

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

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. 1077) objects

Required: No
tlsConfig (p. 72)

An object that specifies the TLS configuration for a domain.

Type: TlsConfig (p. 1102) object

Required: No
validationCertificateArn (p. 72)

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.

73
 AWS IoT API Reference
CreateDomainConfiguration

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

The ARN of the domain configuration.

Type: String
domainConfigurationName (p. 74)

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

74
 AWS IoT API Reference
CreateDomainConfiguration

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

75
 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. 76)

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

The dynamic thing group index name.

Note
Currently one index is supported: AWS_Things.

Type: String

76
 AWS IoT API Reference
CreateDynamicThingGroup

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

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

Required: No
queryString (p. 76)

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

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

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

Type: Array of Tag (p. 1077) objects

Required: No
thingGroupProperties (p. 76)

The dynamic thing group properties.

Type: ThingGroupProperties (p. 1091) 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.

77
 AWS IoT API Reference
CreateDynamicThingGroup

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

indexName (p. 77)

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

The dynamic thing group search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 77)

The dynamic thing group query version.

Type: String
thingGroupArn (p. 77)

The dynamic thing group ARN.

Type: String
thingGroupId (p. 77)

The dynamic thing group ID.

Type: String

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

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

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

78
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

79
 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. 80)

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

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

80
 AWS IoT API Reference
CreateFleetMetric

aggregationType (p. 80)

The type of the aggregation query.

Type: AggregationType (p. 860) object

Required: Yes
description (p. 80)

The fleet metric description.

Type: String

Length Constraints: Maximum length of 1024.

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

Required: No
indexName (p. 80)

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

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

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 80)

The query version.

Type: String

Required: No
tags (p. 80)

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

Type: Array of Tag (p. 1077) objects

81
 AWS IoT API Reference
CreateFleetMetric

Required: No
unit (p. 80)

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

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

Type: String
metricName (p. 82)

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.

82
 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

83
 AWS IoT API Reference
CreateFleetMetric

• AWS SDK for JavaScript V3

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

84
 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",
"destinationPackageVersions": [ "string" ],
"document": "string",
"documentParameters": {
"string" : "string"
},
"documentSource": "string",
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobTemplateArn": "string",
"namespaceId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"schedulingConfig": {
"endBehavior": "string",
"endTime": "string",
"maintenanceWindows": [
{
"durationInMinutes": number,
"startTime": "string"
}

85
 AWS IoT API Reference
CreateJob

],
"startTime": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"targets": [ "string" ],
"targetSelection": "string",
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 85)

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

Allows you to create the criteria to abort a job.

Type: AbortConfig (p. 850) object

Required: No
description (p. 85)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
destinationPackageVersions (p. 85)

The package version Amazon Resource Names (ARNs) that are installed on the device when the job
successfully completes.

Note:The following Length Constraints relates to a single ARN. Up to 25 package version ARNs are
allowed.

86
 AWS IoT API Reference
CreateJob

Type: Array of strings

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

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

Required: No
document (p. 85)

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

Type: String

Length Constraints: Maximum length of 32768.

Required: No
documentParameters (p. 85)

Parameters of an AWS managed template that you can specify to create the job document.
Note
documentParameters can only be used when creating jobs from AWS managed
templates. This parameter can't be used with custom job templates or to create jobs from
them.

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. Maximum length of 512.

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

Required: No
documentSource (p. 85)

An S3 link, or S3 object URL, to the job document. The link is an Amazon S3 object URL and is
required if you don't specify a value for document.

For example, --document-source https://s3.region-code.amazonaws.com/example-

firmware/device-firmware.1.0

For more information, see Methods for accessing a bucket.

Type: String

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

Required: No
jobExecutionsRetryConfig (p. 85)

Allows you to create the criteria to retry a job.

Type: JobExecutionsRetryConfig (p. 972) object

Required: No
jobExecutionsRolloutConfig (p. 85)

Allows you to create a staged rollout of the job.

87
 AWS IoT API Reference
CreateJob

Type: JobExecutionsRolloutConfig (p. 973) object

Required: No
jobTemplateArn (p. 85)

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

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

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

Required: No
presignedUrlConfig (p. 85)

Configuration information for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 1031) object

Required: No
schedulingConfig (p. 85)

The configuration that allows you to schedule a job for a future date and time in addition to
specifying the end behavior for each job execution.

Type: SchedulingConfig (p. 1057) object

Required: No
tags (p. 85)

Metadata which can be used to manage the job.

Type: Array of Tag (p. 1077) objects

Required: No
targets (p. 85)

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.

88
 AWS IoT API Reference
CreateJob

Required: Yes
targetSelection (p. 85)

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.
Note
We recommend that you use continuous jobs instead of snapshot jobs for dynamic thing
group targets. By using continuous jobs, devices that join the group receive the job
execution even after the job has been created.

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No
timeoutConfig (p. 85)

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. 1097) 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. 89)

The job description.

Type: String

Length Constraints: Maximum length of 2028.

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

The job ARN.

89
 AWS IoT API Reference
CreateJob

Type: String
jobId (p. 89)

The unique identifier you assigned to this job.

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 V3
• AWS SDK for PHP V3

90
 AWS IoT API Reference
CreateJob

• AWS SDK for Python

• AWS SDK for Ruby V3

91
 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",
"destinationPackageVersions": [ "string" ],
"document": "string",
"documentSource": "string",
"jobArn": "string",
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"maintenanceWindows": [
{
"durationInMinutes": number,
"startTime": "string"
}
],
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
],

92
 AWS IoT API Reference
CreateJobTemplate

"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

URI Request Parameters

The request uses the following URI parameters.

jobTemplateId (p. 92)

A unique identifier for the job template. 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. 92)

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

Type: AbortConfig (p. 850) object

Required: No
description (p. 92)

A description of the job document.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: Yes
destinationPackageVersions (p. 92)

The package version Amazon Resource Names (ARNs) that are installed on the device when the job
successfully completes.

Note:The following Length Constraints relates to a single ARN. Up to 25 package version ARNs are
allowed.

Type: Array of strings

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

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

Required: No
document (p. 92)

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

93
 AWS IoT API Reference
CreateJobTemplate

Type: String

Length Constraints: Maximum length of 32768.

Required: No
documentSource (p. 92)

An S3 link, or S3 object URL, to the job document. The link is an Amazon S3 object URL and is
required if you don't specify a value for document.

For example, --document-source https://s3.region-code.amazonaws.com/example-

firmware/device-firmware.1.0

For more information, see Methods for accessing a bucket.

Type: String

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

Required: No
jobArn (p. 92)

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

Type: String

Required: No
jobExecutionsRetryConfig (p. 92)

Allows you to create the criteria to retry a job.

Type: JobExecutionsRetryConfig (p. 972) object

Required: No
jobExecutionsRolloutConfig (p. 92)

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 973) object

Required: No
maintenanceWindows (p. 92)

Allows you to configure an optional maintenance window for the rollout of a job document to all
devices in the target group for a job.

Type: Array of MaintenanceWindow (p. 998) objects

Required: No
presignedUrlConfig (p. 92)

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 1031) object

Required: No
tags (p. 92)

Metadata that can be used to manage the job template.

Type: Array of Tag (p. 1077) objects

94
 AWS IoT API Reference
CreateJobTemplate

Required: No
timeoutConfig (p. 92)

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. 1097) 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. 95)

The ARN of the job template.

Type: String

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

Pattern: ^arn:[!-~]+$
jobTemplateId (p. 95)

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.

95
 AWS IoT API Reference
CreateJobTemplate

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

96
 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. 97)

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

The ARN of the certificate.

Type: String

97
 AWS IoT API Reference
CreateKeysAndCertificate

certificateId (p. 97)

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

The certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*
keyPair (p. 97)

The generated key pair.

Type: KeyPair (p. 988) 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:

98
 AWS IoT API Reference
CreateKeysAndCertificate

• 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

99
 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. 100)

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

100
 AWS IoT API Reference
CreateMitigationAction

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

actionParams (p. 100)

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

Type: MitigationActionParams (p. 1009) object

Required: Yes
roleArn (p. 100)

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

Metadata that can be used to manage the mitigation action.

Type: Array of Tag (p. 1077) 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. 101)

The ARN for the new mitigation action.

Type: String
actionId (p. 101)

A unique identifier for the new mitigation action.

Type: String

101
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

102
 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": {

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

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.

104
 AWS IoT API Reference
CreateOTAUpdate

additionalParameters (p. 103)

A list of additional OTA update parameters, which are name-value pairs. They won't be sent to
devices as a part of the Job document.

Type: String to string map

Value Length Constraints: Minimum length of 0. Maximum length of 4096.

Value Pattern: [\s\S]*

Required: No
awsJobAbortConfig (p. 103)

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

Type: AwsJobAbortConfig (p. 886) object

Required: No
awsJobExecutionsRolloutConfig (p. 103)

Configuration for the rollout of OTA updates.

Type: AwsJobExecutionsRolloutConfig (p. 889) object

Required: No
awsJobPresignedUrlConfig (p. 103)

Configuration information for pre-signed URLs.

Type: AwsJobPresignedUrlConfig (p. 891) object

Required: No
awsJobTimeoutConfig (p. 103)

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. 893) object

Required: No
description (p. 103)

The description of the OTA update.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 103)

The files to be streamed by the OTA update.

Type: Array of OTAUpdateFile (p. 1016) objects

Array Members: Minimum number of 1 item.

105
 AWS IoT API Reference
CreateOTAUpdate

Required: Yes
protocols (p. 103)

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.

Valid Values: MQTT | HTTP

Required: No
roleArn (p. 103)

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

Metadata which can be used to manage updates.

Type: Array of Tag (p. 1077) objects

Required: No
targets (p. 103)

The devices targeted to receive OTA updates.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: Yes
targetSelection (p. 103)

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

106
 AWS IoT API Reference
CreateOTAUpdate

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

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

awsIotJobArn (p. 106)

The AWS IoT job ARN associated with the OTA update.

Type: String
awsIotJobId (p. 106)

The AWS IoT job ID associated with the OTA update.

Type: String
otaUpdateArn (p. 106)

The OTA update ARN.

Type: String
otaUpdateId (p. 106)

The OTA update ID.

Type: String

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

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

The OTA update status.

Type: String

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED | DELETE_IN_PROGRESS | DELETE_FAILED

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

107
 AWS IoT API Reference
CreateOTAUpdate

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
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

108
 AWS IoT API Reference
CreatePackage

CreatePackage
Service: AWS IoT

Creates an AWS IoT software package that can be deployed to your fleet.

Requires permission to access the CreatePackage and GetIndexingConfiguration actions.

Request Syntax
PUT /packages/packageName?clientToken=clientToken HTTP/1.1
Content-type: application/json

{
"description": "string",
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 109)

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 36. Maximum length of 64.

Pattern: \S{36,64}
packageName (p. 109)

The name of the new software package.

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

A summary of the package being created. This can be used to outline the package's contents or
purpose.

Type: String

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

Pattern: [^\p{C}]+

109
 AWS IoT API Reference
CreatePackage

Required: No
tags (p. 109)

Metadata that can be used to manage the package.

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 0. Maximum length of 256.

Required: No

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

{
"description": "string",
"packageArn": "string",
"packageName": "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. 110)

The package description.

Type: String

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

Pattern: [^\p{C}]+
packageArn (p. 110)

The Amazon Resource Name (ARN) for the package.

Type: String
packageName (p. 110)

The name of the software package.

Type: String

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

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

110
 AWS IoT API Reference
CreatePackage

Errors
ConflictException

A resource with the same name already exists.

HTTP Status Code: 409

InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ServiceQuotaExceededException

A limit has been exceeded.

HTTP Status Code: 402

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

111
 AWS IoT API Reference
CreatePackageVersion

CreatePackageVersion
Service: AWS IoT

Creates a new version for an existing AWS IoT software package.

Requires permission to access the CreatePackageVersion and GetIndexingConfiguration actions.

Request Syntax
PUT /packages/packageName/versions/versionName?clientToken=clientToken HTTP/1.1
Content-type: application/json

{
"attributes": {
"string" : "string"
},
"description": "string",
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 112)

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 36. Maximum length of 64.

Pattern: \S{36,64}
packageName (p. 112)

The name of the associated software package.

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

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

Required: Yes
versionName (p. 112)

The name of the new package version.

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.

112
 AWS IoT API Reference
CreatePackageVersion

attributes (p. 112)

Metadata that can be used to define a package version’s configuration. For example, the S3 file
location, configuration options that are being sent to the device or fleet.

The combined size of all the attributes on a package version is limited to 3KB.

Type: String to string map

Key Length Constraints: Minimum length of 1.

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

Value Length Constraints: Minimum length of 1.

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

Required: No
description (p. 112)

A summary of the package version being created. This can be used to outline the package's contents
or purpose.

Type: String

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

Pattern: [^\p{C}]+

Required: No
tags (p. 112)

Metadata that can be used to manage the package version.

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 0. Maximum length of 256.

Required: No

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

{
"attributes": {
"string" : "string"
},
"description": "string",
"errorReason": "string",
"packageName": "string",
"packageVersionArn": "string",
"status": "string",

113
 AWS IoT API Reference
CreatePackageVersion

"versionName": "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.

attributes (p. 113)

Metadata that were added to the package version that can be used to define a package version’s
configuration.

Type: String to string map

Key Length Constraints: Minimum length of 1.

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

Value Length Constraints: Minimum length of 1.

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

description (p. 113)

The package version description.

Type: String

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

Pattern: [^\p{C}]+
errorReason (p. 113)

Error reason for a package version failure during creation or update.

Type: String
packageName (p. 113)

The name of the associated software package.

Type: String

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

Pattern: [a-zA-Z0-9-_.]+
packageVersionArn (p. 113)

The Amazon Resource Name (ARN) for the package.

Type: String

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

Pattern: ^arn:[!-~]+$
status (p. 113)

The status of the package version. For more information, see Package version lifecycle.

Type: String

114
 AWS IoT API Reference
CreatePackageVersion

Valid Values: DRAFT | PUBLISHED | DEPRECATED

versionName (p. 113)

The name of the new package version.

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

InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ServiceQuotaExceededException

A limit has been exceeded.

HTTP Status Code: 402

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

115
 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. 116)

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

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

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

Pattern: [\s\S]*

Required: Yes
tags (p. 116)

Metadata which can be used to manage the policy.

116
 AWS IoT API Reference
CreatePolicy

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. 1077) 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. 117)

The policy ARN.

Type: String
policyDocument (p. 117)

The JSON document that describes the policy.

Type: String

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

Pattern: [\s\S]*
policyName (p. 117)

The policy name.

Type: String

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

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

The policy version ID.

Type: String

Pattern: [0-9]+

117
 AWS IoT API Reference
CreatePolicy

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

118
 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. 207) 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. 119)

The policy name.

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

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

Required: Yes
setAsDefault (p. 119)

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

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

Type: String

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

Pattern: [\s\S]*

Required: Yes

119
 AWS IoT API Reference
CreatePolicyVersion

Response Syntax
HTTP/1.1 200
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. 120)

Specifies whether the policy version is the default.

Type: Boolean
policyArn (p. 120)

The policy ARN.

Type: String
policyDocument (p. 120)

The JSON document that describes the policy.

Type: String

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

Pattern: [\s\S]*
policyVersionId (p. 120)

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

120
 AWS IoT API Reference
CreatePolicyVersion

MalformedPolicyException

The policy documentation 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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

121
 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. 122)

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

The ID of the certificate.

Type: String

Length Constraints: Fixed length of 64.

122
 AWS IoT API Reference
CreateProvisioningClaim

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

The provisioning claim certificate.

Type: String

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

Pattern: [\s\S]*
expiration (p. 122)

The provisioning claim expiration time.

Type: Timestamp
keyPair (p. 122)

The provisioning claim key pair.

Type: KeyPair (p. 988) 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:

123
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

124
 AWS IoT API Reference
CreateProvisioningTemplate

CreateProvisioningTemplate
Service: AWS IoT

Creates a 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",
"type": "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. 125)

The description of the provisioning template.

Type: String

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

Pattern: [^\p{C}]*

Required: No
enabled (p. 125)

True to enable the provisioning template, otherwise false.

Type: Boolean

Required: No

125
 AWS IoT API Reference
CreateProvisioningTemplate

preProvisioningHook (p. 125)

Creates a pre-provisioning hook template. Only supports template of type FLEET_PROVISIONING.

For more information about provisioning template types, see type.

Type: ProvisioningHook (p. 1032) object

Required: No
provisioningRoleArn (p. 125)

The role ARN for 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: Yes
tags (p. 125)

Metadata which can be used to manage the 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. 1077) objects

Required: No
templateBody (p. 125)

The JSON formatted contents of the provisioning template.

Type: String

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

Pattern: [\s\S]*

Required: Yes
templateName (p. 125)

The name of the provisioning template.

Type: String

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

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

Required: Yes
type (p. 125)

The type you define in a provisioning template. You can create a template with only one type. You
can't change the template type after its creation. The default value is FLEET_PROVISIONING. For
more information about provisioning template, see: Provisioning template.

Type: String

Valid Values: FLEET_PROVISIONING | JITP

126
 AWS IoT API Reference
CreateProvisioningTemplate

Required: No

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.

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

defaultVersionId (p. 127)

The default version of the provisioning template.

Type: Integer
templateArn (p. 127)

The ARN that identifies the provisioning template.

Type: String
templateName (p. 127)

The name of the 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

127
 AWS IoT API Reference
CreateProvisioningTemplate

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:

• 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

128
 AWS IoT API Reference
CreateProvisioningTemplateVersion

CreateProvisioningTemplateVersion
Service: AWS IoT

Creates a new version of a 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. 129)

Sets a fleet provision template version as the default version.

templateName (p. 129)

The name of the 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. 129)

The JSON formatted contents of the provisioning template.

Type: String

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

Pattern: [\s\S]*

Required: Yes

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

129
 AWS IoT API Reference
CreateProvisioningTemplateVersion

"isDefaultVersion": boolean,
"templateArn": "string",
"templateName": "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.

isDefaultVersion (p. 129)

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

Type: Boolean
templateArn (p. 129)

The ARN that identifies the provisioning template.

Type: String
templateName (p. 129)

The name of the provisioning template.

Type: String

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

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

The version of the 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.

130
 AWS IoT API Reference
CreateProvisioningTemplateVersion

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

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

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

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

This value must be less than or equal to the maximum session duration of the IAM role that the role
alias references.

Type: Integer

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

Required: No
roleArn (p. 132)

The role ARN.

132
 AWS IoT API Reference
CreateRoleAlias

Type: String

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

Required: Yes
tags (p. 132)

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. 1077) 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. 133)

The role alias.

Type: String

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

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

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

133
 AWS IoT API Reference
CreateRoleAlias

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.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

134
 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. 135)

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

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

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.

135
 AWS IoT API Reference
CreateScheduledAudit

Type: String

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

Required: No
frequency (p. 135)

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

Metadata that can be used to manage the scheduled audit.

Type: Array of Tag (p. 1077) objects

Required: No
targetCheckNames (p. 135)

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

The ARN of the scheduled audit.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

136
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

137
 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": [
{
"exportMetric": boolean,
"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" ]
}
},
"exportMetric": boolean,
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"metricsExportConfig": {

138
 AWS IoT API Reference
CreateSecurityProfile

"mqttTopic": "string",
"roleArn": "string"
},
"securityProfileDescription": "string",
"tags": [
{
"Key": "string",
"Value": "string"
}
]
}

URI Request Parameters

The request uses the following URI parameters.

securityProfileName (p. 138)

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

This parameter has been deprecated.

Please use CreateSecurityProfile:additionalMetricsToRetainV2 (p. 139) 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. 138)

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. 1004) objects

Required: No
alertTargets (p. 138)

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. 861) object map

139
 AWS IoT API Reference
CreateSecurityProfile

Valid Keys: SNS

Required: No
behaviors (p. 138)

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

Type: Array of Behavior (p. 894) objects

Array Members: Maximum number of 100 items.

Required: No
metricsExportConfig (p. 138)

Specifies the MQTT topic and role ARN required for metric export.

Type: MetricsExportConfig (p. 1003) object

Required: No
securityProfileDescription (p. 138)

A description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

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

Required: No
tags (p. 138)

Metadata that can be used to manage the security profile.

Type: Array of Tag (p. 1077) 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. 140)

The ARN of the security profile.

140
 AWS IoT API Reference
CreateSecurityProfile

Type: String
securityProfileName (p. 140)

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.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

141
 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. 142)

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

A description of the stream.

Type: String

142
 AWS IoT API Reference
CreateStream

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 142)

The files to stream.

Type: Array of StreamFile (p. 1073) objects

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

Required: Yes
roleArn (p. 142)

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

Type: String

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

Required: Yes
tags (p. 142)

Metadata which can be used to manage streams.

Type: Array of Tag (p. 1077) 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. 143)

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

143
 AWS IoT API Reference
CreateStream

streamArn (p. 143)

The stream ARN.

Type: String
streamId (p. 143)

The stream ID.

Type: String

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

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

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.

144
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

145
 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. 146)

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

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

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

Type: AttributePayload (p. 866) object

146
 AWS IoT API Reference
CreateThing

Required: No
billingGroupName (p. 146)

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

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

The ARN of the new thing.

Type: String
thingId (p. 147)

The thing ID.

Type: String
thingName (p. 147)

The name of the new thing.

Type: String

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

147
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

148
 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.
If the ThingGroup that you create has the exact same attributes as an existing ThingGroup,
you will get a 200 success response.

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

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

The name of the parent thing group.

149
 AWS IoT API Reference
CreateThingGroup

Type: String

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

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

Required: No
tags (p. 149)

Metadata which can be used to manage the thing group.

Type: Array of Tag (p. 1077) objects

Required: No
thingGroupProperties (p. 149)

The thing group properties.

Type: ThingGroupProperties (p. 1091) 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. 150)

The thing group ARN.

Type: String
thingGroupId (p. 150)

The thing group ID.

Type: String

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

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

The thing group name.

Type: String

150
 AWS IoT API Reference
CreateThingGroup

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

151
 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. 152)

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

Metadata which can be used to manage the thing type.

Type: Array of Tag (p. 1077) objects

Required: No
thingTypeProperties (p. 152)

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. 1096) object

Required: No

152
 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. 153)

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

Type: String
thingTypeId (p. 153)

The thing type ID.

Type: String
thingTypeName (p. 153)

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.

153
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

154
 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

{
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"batchMode": boolean,
"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,

155
 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",
"headers": [
{

156
 AWS IoT API Reference
CreateTopicRule

"key": "string",
"value": "string"
}
],
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"location": {
"deviceId": "string",
"latitude": "string",
"longitude": "string",
"roleArn": "string",
"timestamp": {
"unit": "string",
"value": "string"
},
"trackerName": "string"
},
"openSearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"republish": {
"headers": {
"contentType": "string",
"correlationData": "string",
"messageExpiry": "string",
"payloadFormatIndicator": "string",
"responseTopic": "string",
"userProperties": [
{
"key": "string",
"value": "string"
}
]
},
"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"

157
 AWS IoT API Reference
CreateTopicRule

},
"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"
},
"cloudwatchLogs": {
"batchMode": boolean,
"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"
},

158
 AWS IoT API Reference
CreateTopicRule

"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": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]

159
 AWS IoT API Reference
CreateTopicRule

}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"location": {
"deviceId": "string",
"latitude": "string",
"longitude": "string",
"roleArn": "string",
"timestamp": {
"unit": "string",
"value": "string"
},
"trackerName": "string"
},
"openSearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"republish": {
"headers": {
"contentType": "string",
"correlationData": "string",
"messageExpiry": "string",
"payloadFormatIndicator": "string",
"responseTopic": "string",
"userProperties": [
{
"key": "string",
"value": "string"
}
]
},
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",

160
 AWS IoT API Reference
CreateTopicRule

"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,
"sql": "string"
}

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 155)

The name of the rule.

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

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

Required: Yes
tags (p. 155)

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

161
 AWS IoT API Reference
CreateTopicRule

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

actions (p. 155)

The actions associated with the rule.

Type: Array of Action (p. 853) objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: Yes
awsIotSqlVersion (p. 155)

The version of the SQL rules engine to use when evaluating the rule.

Type: String

Required: No
description (p. 155)

The description of the rule.

Type: String

Required: No
errorAction (p. 155)

The action to take when an error occurs.

Type: Action (p. 853) object

Required: No
ruleDisabled (p. 155)

Specifies whether the rule is disabled.

Type: Boolean

Required: No
sql (p. 155)

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

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.

162
 AWS IoT API Reference
CreateTopicRule

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

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

163
 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. 164)

The topic rule destination configuration.

Type: TopicRuleDestinationConfiguration (p. 1108) 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": {

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

The topic rule destination.

Type: TopicRuleDestination (p. 1106) 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++

165
 AWS IoT API Reference
CreateTopicRuleDestination

• AWS SDK for Go

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

166
 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. 167)

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

167
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

168
 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 169)

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

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 1045) object

Required: Yes

169
 AWS IoT API Reference
DeleteAuditSuppression

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

170
 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. 171)

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

171
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

172
 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. 173)

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

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

173
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

174
 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. 175)

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

175
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

176
 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. 339) action to detach all policies. Next, use the
UpdateCertificate (p. 658) 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. 177)

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

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.

177
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

178
 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. 179)

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

179
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

180
 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. 181)

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

181
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

182
 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. 183)

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

183
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

184
 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. 185)

The expected version of the dynamic thing group to delete.

thingGroupName (p. 185)

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

185
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

186
 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. 187)

The expected version of the fleet metric to delete.

metricName (p. 187)

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

187
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

188
 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. 189)

(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. 189)

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

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.

189
 AWS IoT API Reference
DeleteJob

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

• AWS SDK for .NET

190
 AWS IoT API Reference
DeleteJob

• AWS SDK for C++

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

191
 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. 192)

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

(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. 192)

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

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.

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

192
 AWS IoT API Reference
DeleteJobExecution

thingName (p. 192)

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:

193
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

194
 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. 195)

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

195
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

196
 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. 197)

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

197
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

198
 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. 199)

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

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

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

199
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

200
 AWS IoT API Reference
DeletePackage

DeletePackage
Service: AWS IoT

Deletes a specific version from a software package.

Note: All package versions must be deleted before deleting the software package.

Requires permission to access the DeletePackageVersion action.

Request Syntax
DELETE /packages/packageName?clientToken=clientToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 201)

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 36. Maximum length of 64.

Pattern: \S{36,64}
packageName (p. 201)

The name of the target software package.

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
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

201
 AWS IoT API Reference
DeletePackage

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

202
 AWS IoT API Reference
DeletePackageVersion

DeletePackageVersion
Service: AWS IoT

Deletes a specific version from a software package.

Note: If a package version is designated as default, you must remove the designation from the software
package using the UpdatePackage (p. 689) action.

Request Syntax
DELETE /packages/packageName/versions/versionName?clientToken=clientToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 203)

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 36. Maximum length of 64.

Pattern: \S{36,64}
packageName (p. 203)

The name of the associated software package.

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

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

Required: Yes
versionName (p. 203)

The name of the target package version.

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.

203
 AWS IoT API Reference
DeletePackageVersion

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

204
 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. 207) action to delete all non-default versions of the
policy; use the DetachPolicy (p. 339) 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. 205)

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.

205
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

206
 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. 205). 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. 207)

The name of the policy.

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

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

Required: Yes
policyVersionId (p. 207)

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

207
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

208
 AWS IoT API Reference
DeleteProvisioningTemplate

DeleteProvisioningTemplate
Service: AWS IoT

Deletes a 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. 209)

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.

209
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

210
 AWS IoT API Reference
DeleteProvisioningTemplateVersion

DeleteProvisioningTemplateVersion
Service: AWS IoT

Deletes a 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. 211)

The name of the provisioning template version to delete.

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

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

Required: Yes
versionId (p. 211)

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

211
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

212
 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

213
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

214
 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. 215)

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

215
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

216
 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. 217)

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

217
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

218
 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. 219)

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

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

219
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

220
 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. 221)

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

221
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

222
 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. 223)

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

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.

223
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

224
 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. 225)

The expected version of the thing group to delete.

thingGroupName (p. 225)

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

225
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

226
 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. 235), then remove
any associated things by calling UpdateThing (p. 716) to change the thing type on any associated thing,
and finally use DeleteThingType (p. 227) 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. 227)

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

227
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

228
 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. 229)

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.

229
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

230
 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. 231)

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.

231
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

232
 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. 233)

The name of the resource for which you are configuring logging.

Required: Yes
targetType (p. 233)

The type of resource for which you are configuring logging. Must be THING_Group.

Valid Values: DEFAULT | THING_GROUP | CLIENT_ID | SOURCE_IP | PRINCIPAL_ID |

EVENT_TYPE | DEVICE_DEFENDER

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

233
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

234
 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. 235)

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

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.

235
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

236
 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. 237)

Which audit checks are enabled and disabled for this account.

Type: String to AuditCheckConfiguration (p. 867) object map

auditNotificationTargetConfigurations (p. 237)

Information about the targets to which audit notifications are sent for this account.

Type: String to AuditNotificationTarget (p. 876) object map

237
 AWS IoT API Reference
DescribeAccountAuditConfiguration

Valid Keys: SNS

roleArn (p. 237)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

238
 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. 239)

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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",

239
 AWS IoT API Reference
DescribeAuditFinding

"issuerId": "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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 239)

The findings (results) of the audit.

Type: AuditFinding (p. 870) object

Errors
InternalFailureException

An unexpected error has occurred.

240
 AWS IoT API Reference
DescribeAuditFinding

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

241
 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. 242)

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"
}

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

Specifies the mitigation actions and their parameters that are applied as part of this task.

Type: Array of MitigationAction (p. 1007) objects

auditCheckToActionsMapping (p. 242)

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

The date and time when the task was completed or canceled.

Type: Timestamp
startTime (p. 242)

The date and time when the task was started.

Type: Timestamp

243
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

target (p. 242)

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. 875) object

taskStatistics (p. 242)

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. 1080) object map

taskStatus (p. 242)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

244
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

• AWS SDK for Ruby V3

245
 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 246)

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

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 1045) object

Required: Yes

246
 AWS IoT API Reference
DescribeAuditSuppression

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

{
"checkName": "string",
"description": "string",
"expirationDate": number,
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 247)

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

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*
expirationDate (p. 247)

The epoch timestamp in seconds at which this suppression expires.

Type: Timestamp
resourceIdentifier (p. 247)

Information that identifies the noncompliant resource.

247
 AWS IoT API Reference
DescribeAuditSuppression

Type: ResourceIdentifier (p. 1045) object

suppressIndefinitely (p. 247)

Indicates whether a suppression should exist indefinitely or not.

Type: Boolean

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

248
 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. 249)

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",

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

Detailed information about each check performed during this audit.

Type: String to AuditCheckDetails (p. 868) object map

scheduledAuditName (p. 249)

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

The time the audit started.

Type: Timestamp
taskStatistics (p. 249)

Statistical information about the audit.

Type: TaskStatistics (p. 1078) object

taskStatus (p. 249)

The status of the audit: one of "IN_PROGRESS", "COMPLETED", "FAILED", or "CANCELED".

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

taskType (p. 249)

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.

250
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

251
 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. 252)

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,
"enableCachingForHttp": boolean,
"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.

252
 AWS IoT API Reference
DescribeAuthorizer

authorizerDescription (p. 252)

The authorizer description.

Type: AuthorizerDescription (p. 882) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

253
 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. 254)

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

The ARN of the billing group.

254
 AWS IoT API Reference
DescribeBillingGroup

Type: String
billingGroupId (p. 254)

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

Additional information about the billing group.

Type: BillingGroupMetadata (p. 900) object

billingGroupName (p. 254)

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

The properties of the billing group.

Type: BillingGroupProperties (p. 901) object

version (p. 254)

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

255
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

256
 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. 257)

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",
"certificateMode": "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",
"templateName": "string"
}

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

The CA certificate description.

Type: CACertificateDescription (p. 905) object

registrationConfig (p. 257)

Information about the registration configuration.

Type: RegistrationConfig (p. 1041) 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:

258
 AWS IoT API Reference
DescribeCACertificate

• 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

259
 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. 260)

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

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

The description of the certificate.

Type: CertificateDescription (p. 910) 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++

261
 AWS IoT API Reference
DescribeCertificate

• AWS SDK for Go

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

262
 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. 263)

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

The creation date of the custom metric in milliseconds since epoch.

Type: Timestamp

263
 AWS IoT API Reference
DescribeCustomMetric

displayName (p. 263)

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

The time the custom metric was last modified in milliseconds since epoch.

Type: Timestamp
metricArn (p. 263)

The Amazon Resource Number (ARN) of the custom metric.

Type: String
metricName (p. 263)

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

The type of the custom metric.

Important
The type number only takes a single metric value as an input, but while submitting the
metrics value in the DeviceMetrics report, it must be passed as an array with a single value.

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

264
 AWS IoT API Reference
DescribeCustomMetric

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

265
 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,
"enableCachingForHttp": boolean,
"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. 266)

The default authorizer's description.

Type: AuthorizerDescription (p. 882) object

Errors
InternalFailureException

An unexpected error has occurred.

266
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

267
 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. 268)

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

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

The description of a task.

Type: DetectMitigationActionsTaskSummary (p. 928) 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

269
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

270
 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. 271)

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

The Amazon Resource Name (ARN) for the dimension.

Type: String

271
 AWS IoT API Reference
DescribeDimension

creationDate (p. 271)

The date the dimension was created.

Type: Timestamp
lastModifiedDate (p. 271)

The date the dimension was last modified.

Type: Timestamp
name (p. 271)

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

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

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

type (p. 271)

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

272
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

273
 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. 274)

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",
"tlsConfig": {
"securityPolicy": "string"
}
}

274
 AWS IoT API Reference
DescribeDomainConfiguration

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.

authorizerConfig (p. 274)

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 881) object

domainConfigurationArn (p. 274)

The ARN of the domain configuration.

Type: String
domainConfigurationName (p. 274)

The name of the domain configuration.

Type: String

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

Pattern: [\w.:-]+
domainConfigurationStatus (p. 274)

A Boolean value that specifies the current state of the domain configuration.

Type: String

Valid Values: ENABLED | DISABLED

domainName (p. 274)

The name of the domain.

Type: String

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

Pattern: [\s\S]*
domainType (p. 274)

The type of the domain.

Type: String

Valid Values: ENDPOINT | AWS_MANAGED | CUSTOMER_MANAGED

lastStatusChangeDate (p. 274)

The date and time the domain configuration's status was last changed.

Type: Timestamp
serverCertificates (p. 274)

A list containing summary information about the server certificate included in the domain
configuration.

Type: Array of ServerCertificateSummary (p. 1062) objects

275
 AWS IoT API Reference
DescribeDomainConfiguration

serviceType (p. 274)

The type of service delivered by the endpoint.

Type: String

Valid Values: DATA | CREDENTIAL_PROVIDER | JOBS

tlsConfig (p. 274)

An object that specifies the TLS configuration for a domain.

Type: TlsConfig (p. 1102) 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

276
 AWS IoT API Reference
DescribeDomainConfiguration

• AWS SDK for JavaScript V3

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

277
 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. 278)

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. ATS Signed Certificates
are more secure and are trusted by most popular browsers.

Length Constraints: Maximum length of 128.

Pattern: [\s\S]*

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

The endpoint. The format of the endpoint is as follows: identifier.iot.region.amazonaws.com.

278
 AWS IoT API Reference
DescribeEndpoint

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

279
 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. 280)

The creation date of the event configuration.

Type: Timestamp
eventConfigurations (p. 280)

The event configurations.

Type: String to Configuration (p. 921) 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. 280)

The date the event configurations were last modified.

280
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

281
 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. 282)

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.

282
 AWS IoT API Reference
DescribeFleetMetric

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

aggregationField (p. 282)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

aggregationType (p. 282)

The type of the aggregation query.

Type: AggregationType (p. 860) object

creationDate (p. 282)

The date when the fleet metric is created.

Type: Timestamp
description (p. 282)

The fleet metric description.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [\p{Graph}\x20]*
indexName (p. 282)

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

The date when the fleet metric is last modified.

Type: Timestamp
metricArn (p. 282)

The ARN of the fleet metric to describe.

Type: String
metricName (p. 282)

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

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

283
 AWS IoT API Reference
DescribeFleetMetric

Type: Integer

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

queryString (p. 282)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 282)

The query version.

Type: String
unit (p. 282)

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

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.

284
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

285
 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. 286)

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

The index name.

Type: String

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

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

286
 AWS IoT API Reference
DescribeIndex

indexStatus (p. 286)

The index status.

Type: String

Valid Values: ACTIVE | BUILDING | REBUILDING

schema (p. 286)

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.
• MULTI_INDEXING_MODE - Your thing index contains multiple data sources. For more information,
see GetIndexingConfiguration.

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:

287
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

288
 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. 289)

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",
"destinationPackageVersions": [ "string" ],
"documentParameters": {
"string" : "string"
},
"forceCanceled": boolean,
"isConcurrent": boolean,
"jobArn": "string",
"jobExecutionsRetryConfig": {
"criteriaList": [

289
 AWS IoT API Reference
DescribeJob

{
"failureType": "string",
"numberOfRetries": number
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"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",
"scheduledJobRollouts": [
{
"startTime": "string"
}
],
"schedulingConfig": {
"endBehavior": "string",
"endTime": "string",
"maintenanceWindows": [
{
"durationInMinutes": number,
"startTime": "string"
}
],
"startTime": "string"
},
"status": "string",
"targets": [ "string" ],
"targetSelection": "string",
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
}

290
 AWS IoT API Reference
DescribeJob

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

An S3 link to the job document.

Type: String

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

job (p. 289)

Information about the job.

Type: Job (p. 965) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

291
 AWS IoT API Reference
DescribeJob

• AWS SDK for Ruby V3

292
 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. 293)

A string (consisting of the digits "0" through "9" which is used to specify a particular job execution on
a particular device.
jobId (p. 293)

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

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,

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

Information about the job execution.

Type: JobExecution (p. 970) 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 V3

294
 AWS IoT API Reference
DescribeJobExecution

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

295
 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. 296)

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",
"destinationPackageVersions": [ "string" ],
"document": "string",
"documentSource": "string",
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {

296
 AWS IoT API Reference
DescribeJobTemplate

"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobTemplateArn": "string",
"jobTemplateId": "string",
"maintenanceWindows": [
{
"durationInMinutes": number,
"startTime": "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. 296)

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

Type: AbortConfig (p. 850) object

createdAt (p. 296)

The time, in seconds since the epoch, when the job template was created.

Type: Timestamp
description (p. 296)

A description of the job template.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
destinationPackageVersions (p. 296)

The package version Amazon Resource Names (ARNs) that are installed on the device when the job
successfully completes.

Note:The following Length Constraints relates to a single ARN. Up to 25 package version ARNs are
allowed.

Type: Array of strings

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

297
 AWS IoT API Reference
DescribeJobTemplate

Pattern: ^arn:[!-~]+$
document (p. 296)

The job document.

Type: String

Length Constraints: Maximum length of 32768.

documentSource (p. 296)

An S3 link to the job document.

Type: String

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

jobExecutionsRetryConfig (p. 296)

The configuration that determines how many retries are allowed for each failure type for a job.

Type: JobExecutionsRetryConfig (p. 972) object

jobExecutionsRolloutConfig (p. 296)

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 973) object

jobTemplateArn (p. 296)

The ARN of the job template.

Type: String

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

Pattern: ^arn:[!-~]+$
jobTemplateId (p. 296)

The unique identifier of the job template.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
maintenanceWindows (p. 296)

Allows you to configure an optional maintenance window for the rollout of a job document to all
devices in the target group for a job.

Type: Array of MaintenanceWindow (p. 998) objects

presignedUrlConfig (p. 296)

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 1031) object

timeoutConfig (p. 296)

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.

298
 AWS IoT API Reference
DescribeJobTemplate

Type: TimeoutConfig (p. 1097) 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
• AWS SDK for Java V2
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

299
 AWS IoT API Reference
DescribeManagedJobTemplate

DescribeManagedJobTemplate
Service: AWS IoT

View details of a managed job template.

Request Syntax
GET /managed-job-templates/templateName?templateVersion=templateVersion HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

templateName (p. 300)

The unique name of a managed job template, which is required.

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

Required: Yes
templateVersion (p. 300)

An optional parameter to specify version of a managed template. If not specified, the pre-defined
default version is returned.

Pattern: ^[1-9]+.[0-9]+

Request Body
The request does not have a request body.

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

{
"description": "string",
"document": "string",
"documentParameters": [
{
"description": "string",
"example": "string",
"key": "string",
"optional": boolean,
"regex": "string"
}
],
"environments": [ "string" ],
"templateArn": "string",
"templateName": "string",
"templateVersion": "string"
}

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

300
 AWS IoT API Reference
DescribeManagedJobTemplate

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

description (p. 300)

The unique description of a managed template.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
document (p. 300)

The document schema for a managed job template.

Type: String

Length Constraints: Maximum length of 32768.

documentParameters (p. 300)

A map of key-value pairs that you can use as guidance to specify the inputs for creating a job from a
managed template.
Note
documentParameters can only be used when creating jobs from AWS managed
templates. This parameter can't be used with custom job templates or to create jobs from
them.

Type: Array of DocumentParameter (p. 931) objects

environments (p. 300)

A list of environments that are supported with the managed job template.

Type: Array of strings

Pattern: [^\p{C}]+
templateArn (p. 300)

The unique Amazon Resource Name (ARN) of the managed template.

Type: String

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

Pattern: ^arn:[!-~]+$
templateName (p. 300)

The unique name of a managed template, such as AWS-Reboot.

Type: String

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

templateVersion (p. 300)

The version for a managed template.

Type: String

Pattern: ^[1-9]+.[0-9]+

301
 AWS IoT API Reference
DescribeManagedJobTemplate

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

302
 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. 303)

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"

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

The ARN that identifies this migration action.

Type: String
actionId (p. 303)

A unique identifier for this action.

Type: String
actionName (p. 303)

The friendly name that uniquely identifies the mitigation action.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+
actionParams (p. 303)

Parameters that control how the mitigation action is applied, specific to the type of mitigation
action.

Type: MitigationActionParams (p. 1009) object

actionType (p. 303)

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

The date and time when the mitigation action was added to your AWS accounts.

Type: Timestamp
lastModifiedDate (p. 303)

The date and time when the mitigation action was last changed.

Type: Timestamp

304
 AWS IoT API Reference
DescribeMitigationAction

roleArn (p. 303)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

305
 AWS IoT API Reference
DescribeProvisioningTemplate

DescribeProvisioningTemplate
Service: AWS IoT

Returns information about a 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. 306)

The name of the 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",
"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.

306
 AWS IoT API Reference
DescribeProvisioningTemplate

creationDate (p. 306)

The date when the provisioning template was created.

Type: Timestamp
defaultVersionId (p. 306)

The default fleet template version ID.

Type: Integer
description (p. 306)

The description of the provisioning template.

Type: String

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

Pattern: [^\p{C}]*
enabled (p. 306)

True if the provisioning template is enabled, otherwise false.

Type: Boolean
lastModifiedDate (p. 306)

The date when the provisioning template was last modified.

Type: Timestamp
preProvisioningHook (p. 306)

Gets information about a pre-provisioned hook.

Type: ProvisioningHook (p. 1032) object

provisioningRoleArn (p. 306)

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

The ARN of the provisioning template.

Type: String
templateBody (p. 306)

The JSON formatted contents of the provisioning template.

Type: String

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

Pattern: [\s\S]*
templateName (p. 306)

The name of the provisioning template.

307
 AWS IoT API Reference
DescribeProvisioningTemplate

Type: String

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

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

The type you define in a provisioning template. You can create a template with only one type. You
can't change the template type after its creation. The default value is FLEET_PROVISIONING. For
more information about provisioning template, see: Provisioning template.

Type: String

Valid Values: FLEET_PROVISIONING | JITP

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

308
 AWS IoT API Reference
DescribeProvisioningTemplate

• AWS SDK for Ruby V3

309
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

DescribeProvisioningTemplateVersion
Service: AWS IoT

Returns information about a 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. 310)

The template name.

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

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

Required: Yes
versionId (p. 310)

The 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. 310)

The date when the provisioning template version was created.

310
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

Type: Timestamp
isDefaultVersion (p. 310)

True if the provisioning template version is the default version.

Type: Boolean
templateBody (p. 310)

The JSON formatted contents of the provisioning template version.

Type: String

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

Pattern: [\s\S]*
versionId (p. 310)

The 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++

311
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

• AWS SDK for Go

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

312
 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. 313)

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

The role alias description.

313
 AWS IoT API Reference
DescribeRoleAlias

Type: RoleAliasDescription (p. 1048) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

314
 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. 315)

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

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

315
 AWS IoT API Reference
DescribeScheduledAudit

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

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

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

The ARN of the scheduled audit.

Type: String
scheduledAuditName (p. 315)

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

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

316
 AWS IoT API Reference
DescribeScheduledAudit

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

317
 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. 318)

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": [
{
"exportMetric": boolean,
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",

318
 AWS IoT API Reference
DescribeSecurityProfile

"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" ]
}
},
"exportMetric": boolean,
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"creationDate": number,
"lastModifiedDate": number,
"metricsExportConfig": {
"mqttTopic": "string",
"roleArn": "string"
},
"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. 318)

This parameter has been deprecated.

Please use DescribeSecurityProfile:additionalMetricsToRetainV2 (p. 319) 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. 318)

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. 1004) objects

319
 AWS IoT API Reference
DescribeSecurityProfile

alertTargets (p. 318)

Where the alerts are sent. (Alerts are always sent to the console.)

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

Valid Keys: SNS

behaviors (p. 318)

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

Type: Array of Behavior (p. 894) objects

Array Members: Maximum number of 100 items.

creationDate (p. 318)

The time the security profile was created.

Type: Timestamp
lastModifiedDate (p. 318)

The time the security profile was last modified.

Type: Timestamp
metricsExportConfig (p. 318)

Specifies the MQTT topic and role ARN required for metric export.

Type: MetricsExportConfig (p. 1003) object

securityProfileArn (p. 318)

The ARN of the security profile.

Type: String
securityProfileDescription (p. 318)

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

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

The version of the security profile. A new version is generated whenever the security profile is
updated.

Type: Long

320
 AWS IoT API Reference
DescribeSecurityProfile

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

321
 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. 322)

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

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

Information about the stream.

Type: StreamInfo (p. 1074) 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 V3

323
 AWS IoT API Reference
DescribeStream

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

324
 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. 325)

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

The thing attributes.

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

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

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

The ARN of the thing to describe.

Type: String
thingId (p. 325)

The ID of the thing to describe.

Type: String
thingName (p. 325)

The name of the thing.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
thingTypeName (p. 325)

The thing type name.

Type: String

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

Pattern: [a-zA-Z0-9:_-]+
version (p. 325)

The current version of the thing record in the registry.

326
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

327
 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. 328)

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

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

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

The dynamic thing group search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 328)

The dynamic thing group query version.

Type: String
status (p. 328)

The dynamic thing group status.

Type: String

Valid Values: ACTIVE | BUILDING | REBUILDING

thingGroupArn (p. 328)

The thing group ARN.

Type: String
thingGroupId (p. 328)

The thing group ID.

Type: String

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

Pattern: [a-zA-Z0-9\-]+
thingGroupMetadata (p. 328)

Thing group metadata.

Type: ThingGroupMetadata (p. 1090) object

329
 AWS IoT API Reference
DescribeThingGroup

thingGroupName (p. 328)

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

The thing group properties.

Type: ThingGroupProperties (p. 1091) object

version (p. 328)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

330
 AWS IoT API Reference
DescribeThingGroup

• AWS SDK for Ruby V3

331
 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. 332)

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

The task creation date.

332
 AWS IoT API Reference
DescribeThingRegistrationTask

Type: Timestamp
failureCount (p. 332)

The number of things that failed to be provisioned.

Type: Integer
inputFileBucket (p. 332)

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

The input file key.

Type: String

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

Pattern: [a-zA-Z0-9!_.*'()-\/]+
lastModifiedDate (p. 332)

The date when the task was last modified.

Type: Timestamp
message (p. 332)

The message.

Type: String

Length Constraints: Maximum length of 2048.

percentageProgress (p. 332)

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

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

The status of the bulk thing provisioning task.

Type: String

Valid Values: InProgress | Completed | Failed | Cancelled | Cancelling

successCount (p. 332)

The number of things successfully provisioned.

333
 AWS IoT API Reference
DescribeThingRegistrationTask

Type: Integer
taskId (p. 332)

The task ID.

Type: String

Length Constraints: Maximum length of 40.

templateBody (p. 332)

The task's template.

Type: String

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

Pattern: [\s\S]*

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

334
 AWS IoT API Reference
DescribeThingRegistrationTask

• AWS SDK for JavaScript V3

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

335
 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. 336)

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.

336
 AWS IoT API Reference
DescribeThingType

thingTypeArn (p. 336)

The thing type ARN.

Type: String
thingTypeId (p. 336)

The thing type ID.

Type: String
thingTypeMetadata (p. 336)

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. 1095) object

thingTypeName (p. 336)

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

The ThingTypeProperties contains information about the thing type including description, and a list
of searchable thing attribute names.

Type: ThingTypeProperties (p. 1096) 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.

337
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

338
 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. 339)

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

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.

339
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

340
 AWS IoT API Reference
DetachPrincipalPolicy

DetachPrincipalPolicy
Service: AWS IoT

Removes the specified policy from the specified certificate.

Note: This action is deprecated and works as expected for backward compatibility, but we won't add
enhancements. Use DetachPolicy (p. 339) 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. 341)

The name of the policy to detach.

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

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

Required: Yes
principal (p. 341)

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.

341
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

342
 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. 343)

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

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.

343
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

344
 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. 345)

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

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

345
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

346
 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. 347)

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.

347
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

348
 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. 349)

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.

349
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

350
 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. 351)

The maximum number of results to return at one time. The default is 10.

Valid Range: Minimum value of 1. Maximum value of 10.

nextToken (p. 351)

The token for the next set of results.

securityProfileName (p. 351)

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
}
]
}

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

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

A list of all ML Detect behaviors and their model status for a given Security Profile.

Type: Array of BehaviorModelTrainingSummary (p. 898) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

352
 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. 353)

The aggregation field.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
bucketsAggregationType (p. 353)

The basic control of the response shape and the bucket aggregation type to perform.

Type: BucketsAggregationType (p. 903) object

Required: Yes
indexName (p. 353)

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

353
 AWS IoT API Reference
GetBucketsAggregation

queryString (p. 353)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 353)

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

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. 902) objects

totalCount (p. 354)

The total number of things that fit the query string criteria.

Type: Integer

Errors
IndexNotReadyException

The index is not ready.

354
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

355
AWS IoT API Reference
GetBucketsAggregation

356
 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. 357)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 357)

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

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 357)

The query version.

357
 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. 358)

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.

358
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

359
 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. 360)

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

The Cognito identity pool ID.

Type: String

Required: No
principal (p. 360)

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

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

The effective policies.

Type: Array of EffectivePolicy (p. 937) 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.

361
 AWS IoT API Reference
GetEffectivePolicies

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

362
 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"
}
],
"deviceDefenderIndexingMode": "string",
"filter": {
"geoLocations": [
{
"name": "string",
"order": "string"
}
],
"namedShadowNames": [ "string" ]
},
"managedFields": [
{

363
 AWS IoT API Reference
GetIndexingConfiguration

"name": "string",
"type": "string"
}
],
"namedShadowIndexingMode": "string",
"thingConnectivityIndexingMode": "string",
"thingIndexingMode": "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.

thingGroupIndexingConfiguration (p. 363)

The index configuration.

Type: ThingGroupIndexingConfiguration (p. 1089) object

thingIndexingConfiguration (p. 363)

Thing indexing configuration.

Type: ThingIndexingConfiguration (p. 1092) 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:

364
 AWS IoT API Reference
GetIndexingConfiguration

• 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

365
 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. 366)

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

The job document content.

Type: String

Length Constraints: Maximum length of 32768.

Errors
InvalidRequestException

The request is not valid.

366
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

367
 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. 368)

The logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

roleArn (p. 368)

The ARN of the IAM role that grants access.

Type: String

Errors
InternalException

An unexpected error has occurred.

368
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

369
 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. 370)

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",

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

371
 AWS IoT API Reference
GetOTAUpdate

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

otaUpdateInfo (p. 370)

The OTA update info.

Type: OTAUpdateInfo (p. 1018) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

372
AWS IoT API Reference
GetOTAUpdate

373
 AWS IoT API Reference
GetPackage

GetPackage
Service: AWS IoT

Gets information about the specified software package.

Requires permission to access the GetPackage action.

Request Syntax
GET /packages/packageName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

packageName (p. 374)

The name of the target software package.

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,
"defaultVersionName": "string",
"description": "string",
"lastModifiedDate": number,
"packageArn": "string",
"packageName": "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. 374)

The date the package was created.

Type: Timestamp

374
 AWS IoT API Reference
GetPackage

defaultVersionName (p. 374)

The name of the default package version.

Type: String

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

Pattern: [a-zA-Z0-9-_.]+
description (p. 374)

The package description.

Type: String

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

Pattern: [^\p{C}]+
lastModifiedDate (p. 374)

The date when the package was last updated.

Type: Timestamp
packageArn (p. 374)

The ARN for the package.

Type: String
packageName (p. 374)

The name of the software package.

Type: String

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

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

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

375
 AWS IoT API Reference
GetPackage

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

376
 AWS IoT API Reference
GetPackageConfiguration

GetPackageConfiguration
Service: AWS IoT

Gets information about the specified software package's configuration.

Requires permission to access the GetPackageConfiguration action.

Request Syntax
GET /package-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

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

versionUpdateByJobsConfig (p. 377)

The version that is associated to a specific job.

Type: VersionUpdateByJobsConfig (p. 1120) object

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

377
 AWS IoT API Reference
GetPackageConfiguration

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

378
 AWS IoT API Reference
GetPackageVersion

GetPackageVersion
Service: AWS IoT

Gets information about the specified package version.

Requires permission to access the GetPackageVersion action.

Request Syntax
GET /packages/packageName/versions/versionName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

packageName (p. 379)

The name of the associated package.

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

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

Required: Yes
versionName (p. 379)

The name of the target package version.

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

{
"attributes": {
"string" : "string"
},
"creationDate": number,
"description": "string",
"errorReason": "string",
"lastModifiedDate": number,
"packageName": "string",
"packageVersionArn": "string",
"status": "string",
"versionName": "string"
}

379
 AWS IoT API Reference
GetPackageVersion

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

Metadata that were added to the package version that can be used to define a package version’s
configuration.

Type: String to string map

Key Length Constraints: Minimum length of 1.

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

Value Length Constraints: Minimum length of 1.

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

creationDate (p. 379)

The date when the package version was created.

Type: Timestamp
description (p. 379)

The package version description.

Type: String

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

Pattern: [^\p{C}]+
errorReason (p. 379)

Error reason for a package version failure during creation or update.

Type: String
lastModifiedDate (p. 379)

The date when the package version was last updated.

Type: Timestamp
packageName (p. 379)

The name of the software package.

Type: String

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

Pattern: [a-zA-Z0-9-_.]+
packageVersionArn (p. 379)

The ARN for the package version.

Type: String

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

380
 AWS IoT API Reference
GetPackageVersion

Pattern: ^arn:[!-~]+$
status (p. 379)

The status associated to the package version. For more information, see Package version lifecycle.

Type: String

Valid Values: DRAFT | PUBLISHED | DEPRECATED

versionName (p. 379)

The name of the package version.

Type: String

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

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

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

381
AWS IoT API Reference
GetPackageVersion

382
 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. 383)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 383)

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

The percentile groups returned.

383
 AWS IoT API Reference
GetPercentiles

Type: Array of doubles

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

Required: No
queryString (p. 383)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 383)

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

The percentile values of the aggregated fields.

Type: Array of PercentPair (p. 1027) objects

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

384
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

385
 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. 386)

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

The date the policy was created.

Type: Timestamp

386
 AWS IoT API Reference
GetPolicy

defaultVersionId (p. 386)

The default policy version ID.

Type: String

Pattern: [0-9]+
generationId (p. 386)

The generation ID of the policy.

Type: String
lastModifiedDate (p. 386)

The date the policy was last modified.

Type: Timestamp
policyArn (p. 386)

The policy ARN.

Type: String
policyDocument (p. 386)

The JSON document that describes the policy.

Type: String

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

Pattern: [\s\S]*
policyName (p. 386)

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

387
 AWS IoT API Reference
GetPolicy

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

388
 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. 389)

The name of the policy.

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

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

Required: Yes
policyVersionId (p. 389)

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.

389
 AWS IoT API Reference
GetPolicyVersion

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

creationDate (p. 389)

The date the policy was created.

Type: Timestamp
generationId (p. 389)

The generation ID of the policy version.

Type: String
isDefaultVersion (p. 389)

Specifies whether the policy version is the default.

Type: Boolean
lastModifiedDate (p. 389)

The date the policy was last modified.

Type: Timestamp
policyArn (p. 389)

The policy ARN.

Type: String
policyDocument (p. 389)

The JSON document that describes the policy.

Type: String

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

Pattern: [\s\S]*
policyName (p. 389)

The policy name.

Type: String

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

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

The policy version ID.

Type: String

Pattern: [0-9]+

Errors
InternalFailureException

An unexpected error has occurred.

390
 AWS IoT API Reference
GetPolicyVersion

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

391
 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. 392)

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.

392
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

393
 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. 394)

The aggregation field name.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 394)

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

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

394
 AWS IoT API Reference
GetStatistics

queryVersion (p. 394)

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

The statistics returned by the Fleet Indexing service based on the query and aggregation field.

Type: Statistics (p. 1069) 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.

395
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

396
 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. 397)

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": {
"batchMode": boolean,
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {

397
 AWS IoT API Reference
GetTopicRule

"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"
},
"iotEvents": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",

398
 AWS IoT API Reference
GetTopicRule

"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",
"headers": [
{
"key": "string",
"value": "string"
}
],
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"location": {
"deviceId": "string",
"latitude": "string",
"longitude": "string",
"roleArn": "string",
"timestamp": {
"unit": "string",
"value": "string"
},
"trackerName": "string"
},
"openSearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"republish": {
"headers": {
"contentType": "string",
"correlationData": "string",
"messageExpiry": "string",
"payloadFormatIndicator": "string",

399
 AWS IoT API Reference
GetTopicRule

"responseTopic": "string",
"userProperties": [
{
"key": "string",
"value": "string"
}
]
},
"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",
"createdAt": number,
"description": "string",
"errorAction": {
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"batchMode": boolean,

400
 AWS IoT API Reference
GetTopicRule

"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"
},
"iotEvents": {

401
 AWS IoT API Reference
GetTopicRule

"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",
"headers": [
{
"key": "string",
"value": "string"
}
],
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"location": {
"deviceId": "string",
"latitude": "string",
"longitude": "string",
"roleArn": "string",
"timestamp": {
"unit": "string",
"value": "string"
},
"trackerName": "string"
},
"openSearch": {

402
 AWS IoT API Reference
GetTopicRule

"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"republish": {
"headers": {
"contentType": "string",
"correlationData": "string",
"messageExpiry": "string",
"payloadFormatIndicator": "string",
"responseTopic": "string",
"userProperties": [
{
"key": "string",
"value": "string"
}
]
},
"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,

403
 AWS IoT API Reference
GetTopicRule

"ruleName": "string",
"sql": "string"
},
"ruleArn": "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.

rule (p. 397)

The rule.

Type: TopicRule (p. 1104) object

ruleArn (p. 397)

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

404
 AWS IoT API Reference
GetTopicRule

• AWS SDK for JavaScript V3

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

405
 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. 406)

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

The topic rule destination.

406
 AWS IoT API Reference
GetTopicRuleDestination

Type: TopicRuleDestination (p. 1106) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

407
 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. 408)

The default log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

disableAllLogs (p. 408)

Disables all logs.

Type: Boolean
roleArn (p. 408)

The IAM role ARN AWS IoT uses to write to your CloudWatch logs.

Type: String

408
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

409
 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. 410)

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

listSuppressedAlerts (p. 410)

A list of all suppressed alerts.

maxResults (p. 410)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 410)

The token for the next set of results.

securityProfileName (p. 410)

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

The name of the thing whose active violations are listed.

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

verificationState (p. 410)

The verification state of the violation (detect alarm).

Valid Values: FALSE_POSITIVE | BENIGN_POSITIVE | TRUE_POSITIVE | UNKNOWN

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

410
 AWS IoT API Reference
ListActiveViolations

Content-type: application/json

{
"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" ]
}
},
"exportMetric": boolean,
"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",
"verificationState": "string",
"verificationStateDescription": "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.

411
 AWS IoT API Reference
ListActiveViolations

activeViolations (p. 410)

The list of active violations.

Type: Array of ActiveViolation (p. 857) objects

nextToken (p. 410)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

412
 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. 413)

The token to retrieve the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 413)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

recursive (p. 413)

When true, recursively list attached policies.

target (p. 413)

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"
}
]

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

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

The policies.

Type: Array of Policy (p. 1028) 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.

414
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

415
 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 416)

A filter to limit results to the findings for the specified audit check.

Type: String

Required: No
endTime (p. 416)

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.

416
 AWS IoT API Reference
ListAuditFindings

Type: Timestamp

Required: No
listSuppressedFindings (p. 416)

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

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

The token for the next set of results.

Type: String

Required: No
resourceIdentifier (p. 416)

Information identifying the noncompliant resource.

Type: ResourceIdentifier (p. 1045) object

Required: No
startTime (p. 416)

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

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

417
 AWS IoT API Reference
ListAuditFindings

Content-type: application/json

{
"findings": [
{
"checkName": "string",
"findingId": "string",
"findingTime": number,
"isSuppressed": boolean,
"nonCompliantResource": {
"additionalInfo": {
"string" : "string"
},
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "string"
},
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"resourceType": "string"
}
],
"severity": "string",
"taskId": "string",
"taskStartTime": number

418
 AWS IoT API Reference
ListAuditFindings

}
],
"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. 417)

The findings (results) of the audit.

Type: Array of AuditFinding (p. 870) objects

nextToken (p. 417)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

419
 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. 420)

Specify this filter to limit results to those with a specific status.

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED | SKIPPED | PENDING

findingId (p. 420)

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

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

The token for the next set of results.

taskId (p. 420)

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

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

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. 872) objects

nextToken (p. 420)

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:

421
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

422
 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. 423)

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

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

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

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

The token for the next set of results.

startTime (p. 423)

Specify this filter to limit results to tasks that began on or after a specific date and time.

Required: Yes
taskStatus (p. 423)

Specify this filter to limit results to tasks that are in a specific state.

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

423
 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. 424)

The token for the next set of results.

Type: String
tasks (p. 424)

The collection of audit mitigation tasks that matched the filter criteria.

Type: Array of AuditMitigationActionsTaskMetadata (p. 874) 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:

424
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

425
 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 426)

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

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

426
 AWS IoT API Reference
ListAuditSuppressions

Type: String

Required: No
maxResults (p. 426)

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

The token for the next set of results.

Type: String

Required: No
resourceIdentifier (p. 426)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 1045) 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "string"
},
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"suppressIndefinitely": boolean
}
]

427
 AWS IoT API Reference
ListAuditSuppressions

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

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String
suppressions (p. 427)

List of audit suppressions.

Type: Array of AuditSuppression (p. 877) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

428
 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. 429)

The end of the time period.

Required: Yes
maxResults (p. 429)

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

The token for the next set of results.

startTime (p. 429)

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

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

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

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

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

The audits that were performed during the specified time period.

Type: Array of AuditTaskMetadata (p. 879) 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

430
 AWS IoT API Reference
ListAuditTasks

• AWS SDK for Java V2

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

431
 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. 432)

Return the list of authorizers in ascending alphabetical order.

marker (p. 432)

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

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

status (p. 432)

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"
}

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

The authorizers.

Type: Array of AuthorizerSummary (p. 884) objects

nextMarker (p. 432)

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

433
 AWS IoT API Reference
ListAuthorizers

• AWS SDK for Go

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

434
 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. 435)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namePrefixFilter (p. 435)

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

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.

435
 AWS IoT API Reference
ListBillingGroups

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

billingGroups (p. 435)

The list of billing groups.

Type: Array of GroupNameAndArn (p. 949) objects

nextToken (p. 435)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

436
 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&templateName=templateName
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

ascendingOrder (p. 437)

Determines the order of the results.

marker (p. 437)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 437)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

templateName (p. 437)

The name of the provisioning template.

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

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

Request Body
The request does not have a request body.

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

{
"certificates": [
{

437
 AWS IoT API Reference
ListCACertificates

"certificateArn": "string",
"certificateId": "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. 437)

The CA certificates registered in your AWS account.

Type: Array of CACertificate (p. 904) objects

nextMarker (p. 437)

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

438
 AWS IoT API Reference
ListCACertificates

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

439
 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. 440)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
marker (p. 440)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 440)

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"
}

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

The descriptions of the certificates.

Type: Array of Certificate (p. 908) objects

nextMarker (p. 440)

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

441
 AWS IoT API Reference
ListCertificates

• AWS SDK for Go

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

442
 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. 443)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
caCertificateId (p. 443)

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

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 443)

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": [
{

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

The device certificates signed by the specified CA certificate.

Type: Array of Certificate (p. 908) objects

nextMarker (p. 443)

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

444
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

445
 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. 446)

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

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

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

A token that can be used to retrieve the next set of results, or null if there are no additional results.

446
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

447
 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. 448)

The end of the time period for which ML Detect mitigation actions executions are returned.
maxResults (p. 448)

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

The token for the next set of results.

startTime (p. 448)

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

The unique identifier of the task.

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

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

The name of the thing whose mitigation actions are listed.

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

violationId (p. 448)

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.

448
 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. 449)

List of actions executions.

Type: Array of DetectMitigationActionExecution (p. 925) objects

nextToken (p. 449)

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

449
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

450
 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. 451)

The end of the time period for which ML Detect mitigation actions tasks are returned.

Required: Yes
maxResults (p. 451)

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

The token for the next set of results.

startTime (p. 451)

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" ]

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

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

The collection of ML Detect mitigation tasks that matched the filter criteria.

Type: Array of DetectMitigationActionsTaskSummary (p. 928) objects

452
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

453
 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. 454)

The maximum number of results to retrieve at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 454)

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

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:_-]+

454
 AWS IoT API Reference
ListDimensions

nextToken (p. 454)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

455
 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. 456)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 456)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

serviceType (p. 456)

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.

456
 AWS IoT API Reference
ListDomainConfigurations

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

domainConfigurations (p. 456)

A list of objects that contain summary information about the user's domain configurations.

Type: Array of DomainConfigurationSummary (p. 933) objects

nextMarker (p. 456)

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 V3

457
 AWS IoT API Reference
ListDomainConfigurations

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

458
 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. 459)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 459)

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

The list of fleet metrics objects.

Type: Array of FleetMetricNameAndArn (p. 947) objects

459
 AWS IoT API Reference
ListFleetMetrics

nextToken (p. 459)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

460
 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. 461)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 500.

nextToken (p. 461)

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

The index names.

Type: Array of strings

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

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 461)

The token used to get the next set of results, or null if there are no additional results.

461
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

462
 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. 463)

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

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 463)

The token to retrieve the next set of results.

status (p. 463)

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,
"retryAttempt": number,

463
 AWS IoT API Reference
ListJobExecutionsForJob

"startedAt": number,
"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. 463)

A list of job execution summaries.

Type: Array of JobExecutionSummaryForJob (p. 977) objects

nextToken (p. 463)

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

464
 AWS IoT API Reference
ListJobExecutionsForJob

• AWS SDK for Go

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

465
 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?
jobId=jobId&maxResults=maxResults&namespaceId=namespaceId&nextToken=nextToken&status=status
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 466)

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_-]+
maxResults (p. 466)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namespaceId (p. 466)

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.

Pattern: [a-zA-Z0-9_-]+
nextToken (p. 466)

The token to retrieve the next set of results.

status (p. 466)

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

The thing name.

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

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

466
 AWS IoT API Reference
ListJobExecutionsForThing

Required: Yes

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,
"retryAttempt": 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. 467)

A list of job execution summaries.

Type: Array of JobExecutionSummaryForThing (p. 978) objects

nextToken (p. 467)

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

467
 AWS IoT API Reference
ListJobExecutionsForThing

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

468
 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. 469)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namespaceId (p. 469)

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.

Pattern: [a-zA-Z0-9_-]+
nextToken (p. 469)

The token to retrieve the next set of results.

status (p. 469)

An optional filter that lets you search for jobs that have the specified status.

Valid Values: IN_PROGRESS | CANCELED | COMPLETED | DELETION_IN_PROGRESS |

SCHEDULED
targetSelection (p. 469)

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.
Note
We recommend that you use continuous jobs instead of snapshot jobs for dynamic thing
group targets. By using continuous jobs, devices that join the group receive the job
execution even after the job has been created.

469
 AWS IoT API Reference
ListJobs

Valid Values: CONTINUOUS | SNAPSHOT

thingGroupId (p. 469)

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\-]+
thingGroupName (p. 469)

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,
"isConcurrent": boolean,
"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. 470)

A list of jobs.

Type: Array of JobSummary (p. 981) objects

nextToken (p. 470)

The token for the next set of results, or null if there are no additional results.

Type: String

470
 AWS IoT API Reference
ListJobs

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

471
 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. 472)

The maximum number of results to return in the list.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 472)

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

A list of objects that contain information about the job templates.

Type: Array of JobTemplateSummary (p. 983) objects

472
 AWS IoT API Reference
ListJobTemplates

nextToken (p. 472)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

473
 AWS IoT API Reference
ListManagedJobTemplates

ListManagedJobTemplates
Service: AWS IoT

Returns a list of managed job templates.

Request Syntax
GET /managed-job-templates?
maxResults=maxResults&nextToken=nextToken&templateName=templateName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 474)

Maximum number of entries that can be returned.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 474)

The token to retrieve the next set of results.

templateName (p. 474)

An optional parameter for template name. If specified, only the versions of the managed job
templates that have the specified template name will be returned.

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

Request Body
The request does not have a request body.

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

{
"managedJobTemplates": [
{
"description": "string",
"environments": [ "string" ],
"templateArn": "string",
"templateName": "string",
"templateVersion": "string"
}
],
"nextToken": "string"
}

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

474
 AWS IoT API Reference
ListManagedJobTemplates

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

managedJobTemplates (p. 474)

A list of managed job templates that are returned.

Type: Array of ManagedJobTemplateSummary (p. 999) objects

nextToken (p. 474)

The token to retrieve the next set of results.

Type: String

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

475
 AWS IoT API Reference
ListMetricValues

ListMetricValues
Service: AWS IoT

Lists the values reported for an AWS IoT Device Defender metric (device-side metric, cloud-side metric, or
custom metric) by the given thing during the specified time period.

Request Syntax
GET /metric-values?
dimensionName=dimensionName&dimensionValueOperator=dimensionValueOperator&endTime=endTime&maxResults=ma
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

dimensionName (p. 476)

The dimension name.

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

Pattern: [a-zA-Z0-9:_-]+
dimensionValueOperator (p. 476)

The dimension value operator.

Valid Values: IN | NOT_IN

endTime (p. 476)

The end of the time period for which metric values are returned.

Required: Yes
maxResults (p. 476)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

metricName (p. 476)

The name of the security profile metric for which values are returned.

Required: Yes
nextToken (p. 476)

The token for the next set of results.

startTime (p. 476)

The start of the time period for which metric values are returned.

Required: Yes
thingName (p. 476)

The name of the thing for which security profile metric values are returned.

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

476
 AWS IoT API Reference
ListMetricValues

Required: Yes

Request Body
The request does not have a request body.

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

{
"metricDatumList": [
{
"timestamp": number,
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "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.

metricDatumList (p. 477)

The data the thing reports for the metric during the specified time period.

Type: Array of MetricDatum (p. 1001) objects

nextToken (p. 477)

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

477
 AWS IoT API Reference
ListMetricValues

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

478
 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. 479)

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

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

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.

479
 AWS IoT API Reference
ListMitigationActions

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

actionIdentifiers (p. 479)

A set of actions that matched the specified filter criteria.

Type: Array of MitigationActionIdentifier (p. 1008) objects

nextToken (p. 479)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

480
 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. 481)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 481)

A token used to retrieve the next set of results.

otaUpdateStatus (p. 481)

The OTA update job status.

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED | DELETE_IN_PROGRESS | DELETE_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.

481
 AWS IoT API Reference
ListOTAUpdates

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

nextToken (p. 481)

A token to use to get the next set of results.

Type: String
otaUpdates (p. 481)

A list of OTA update jobs.

Type: Array of OTAUpdateSummary (p. 1021) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

482
AWS IoT API Reference
ListOTAUpdates

483
 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. 484)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
marker (p. 484)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 484)

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"
}
]
}

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

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

The certificates that are being transferred but not yet accepted.

Type: Array of OutgoingCertificate (p. 1022) 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++

485
 AWS IoT API Reference
ListOutgoingCertificates

• AWS SDK for Go

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

486
 AWS IoT API Reference
ListPackages

ListPackages
Service: AWS IoT

Lists the software packages associated to the account.

Requires permission to access the ListPackages action.

Request Syntax
GET /packages?maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 487)

The maximum number of results returned at one time.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken (p. 487)

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",
"packageSummaries": [
{
"creationDate": number,
"defaultVersionName": "string",
"lastModifiedDate": number,
"packageName": "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. 487)

The token for the next set of results.

Type: String

487
 AWS IoT API Reference
ListPackages

packageSummaries (p. 487)

The software package summary.

Type: Array of PackageSummary (p. 1024) objects

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

488
 AWS IoT API Reference
ListPackageVersions

ListPackageVersions
Service: AWS IoT

Lists the software package versions associated to the account.

Requires permission to access the ListPackageVersions action.

Request Syntax
GET /packages/packageName/versions?maxResults=maxResults&nextToken=nextToken&status=status
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

maxResults (p. 489)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 100.

nextToken (p. 489)

The token for the next set of results.

packageName (p. 489)

The name of the target software package.

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

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

Required: Yes
status (p. 489)

The status of the package version. For more information, see Package version lifecycle.

Valid Values: DRAFT | PUBLISHED | DEPRECATED

Request Body
The request does not have a request body.

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

{
"nextToken": "string",
"packageVersionSummaries": [
{
"creationDate": number,
"lastModifiedDate": number,
"packageName": "string",
"status": "string",

489
 AWS IoT API Reference
ListPackageVersions

"versionName": "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. 489)

The token for the next set of results.

Type: String
packageVersionSummaries (p. 489)

Lists the package versions associated to the package.

Type: Array of PackageVersionSummary (p. 1025) objects

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

490
 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. 491)

Specifies the order for results. If true, the results are returned in ascending creation order.
marker (p. 491)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 491)

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.

491
 AWS IoT API Reference
ListPolicies

nextMarker (p. 491)

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

The descriptions of the policies.

Type: Array of Policy (p. 1028) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

492
 AWS IoT API Reference
ListPolicies

• AWS SDK for Ruby V3

493
 AWS IoT API Reference
ListPolicyPrincipals

ListPolicyPrincipals
Service: AWS IoT

Lists the principals associated with the specified policy.

Note: This action is deprecated and works as expected for backward compatibility, but we won't add
enhancements. Use ListTargetsForPolicy (p. 528) 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. 494)

Specifies the order for results. If true, the results are returned in ascending creation order.
marker (p. 494)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 494)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

policyName (p. 494)

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

494
 AWS IoT API Reference
ListPolicyPrincipals

"nextMarker": "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.

nextMarker (p. 494)

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

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

495
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

496
 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. 497)

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

The policy versions.

Type: Array of PolicyVersion (p. 1029) objects

497
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

498
 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 and works as expected for backward compatibility, but we won't add
enhancements. Use ListAttachedPolicies (p. 413) 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. 499)

Specifies the order for results. If true, results are returned in ascending creation order.
marker (p. 499)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 499)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

principal (p. 499)

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": [

499
 AWS IoT API Reference
ListPrincipalPolicies

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

nextMarker (p. 499)

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

The policies.

Type: Array of Policy (p. 1028) 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.

500
 AWS IoT API Reference
ListPrincipalPolicies

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

501
 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. 502)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 502)

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

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

The token to use to get the next set of results, or null if there are no additional results.

502
 AWS IoT API Reference
ListPrincipalThings

Type: String
things (p. 502)

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 V3
• AWS SDK for PHP V3

503
 AWS IoT API Reference
ListPrincipalThings

• AWS SDK for Python

• AWS SDK for Ruby V3

504
 AWS IoT API Reference
ListProvisioningTemplates

ListProvisioningTemplates
Service: AWS IoT

Lists the 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. 505)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 505)

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

nextToken (p. 505)

A token to retrieve the next set of results.

505
 AWS IoT API Reference
ListProvisioningTemplates

Type: String
templates (p. 505)

A list of provisioning templates

Type: Array of ProvisioningTemplateSummary (p. 1033) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

506
 AWS IoT API Reference
ListProvisioningTemplateVersions

ListProvisioningTemplateVersions
Service: AWS IoT

A list of 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. 507)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 507)

A token to retrieve the next set of results.

templateName (p. 507)

The name of the 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.

507
 AWS IoT API Reference
ListProvisioningTemplateVersions

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

nextToken (p. 507)

A token to retrieve the next set of results.

Type: String
versions (p. 507)

The list of provisioning template versions.

Type: Array of ProvisioningTemplateVersionSummary (p. 1035) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

508
 AWS IoT API Reference
ListProvisioningTemplateVersions

509
 AWS IoT API Reference
ListRelatedResourcesForAuditFinding

ListRelatedResourcesForAuditFinding
Service: AWS IoT

The related resources of an Audit finding. The following resources can be returned from calling this API:

• DEVICE_CERTIFICATE
• CA_CERTIFICATE
• IOT_POLICY
• COGNITO_IDENTITY_POOL
• CLIENT_ID
• ACCOUNT_SETTINGS
• ROLE_ALIAS
• IAM_ROLE
• ISSUER_CERTIFICATE

Note
This API is similar to DescribeAuditFinding's RelatedResources but provides pagination and is not
limited to 10 resources. When calling DescribeAuditFinding for the intermediate CA revoked for
active device certificates check, RelatedResources will not be populated. You must use this API,
ListRelatedResourcesForAuditFinding, to list the certificates.

Request Syntax
GET /audit/relatedResources?findingId=findingId&maxResults=maxResults&nextToken=nextToken
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

findingId (p. 510)

The finding Id.

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

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

Required: Yes
maxResults (p. 510)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 510)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Request Body
The request does not have a request body.

510
 AWS IoT API Reference
ListRelatedResourcesForAuditFinding

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

{
"nextToken": "string",
"relatedResources": [
{
"additionalInfo": {
"string" : "string"
},
"resourceIdentifier": {
"account": "string",
"caCertificateId": "string",
"clientId": "string",
"cognitoIdentityPoolId": "string",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "string"
},
"policyVersionIdentifier": {
"policyName": "string",
"policyVersionId": "string"
},
"roleAliasArn": "string"
},
"resourceType": "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. 511)

A token that can be used to retrieve the next set of results, or null for the first API call.

Type: String
relatedResources (p. 511)

The related resources.

Type: Array of RelatedResource (p. 1042) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

511
 AWS IoT API Reference
ListRelatedResourcesForAuditFinding

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

512
 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. 513)

Return the list of role aliases in ascending alphabetical order.

marker (p. 513)

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

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

A marker used to get the next set of results.

513
 AWS IoT API Reference
ListRoleAliases

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
roleAliases (p. 513)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

514
 AWS IoT API Reference
ListRoleAliases

• AWS SDK for Ruby V3

515
 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. 516)

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

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

A token that can be used to retrieve the next set of results, or null if there are no additional results.

516
 AWS IoT API Reference
ListScheduledAudits

Type: String
scheduledAudits (p. 516)

The list of scheduled audits.

Type: Array of ScheduledAuditMetadata (p. 1054) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

517
 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. 518)

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

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

metricName (p. 518)

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

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

518
 AWS IoT API Reference
ListSecurityProfiles

"nextToken": "string",
"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. 518)

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

A list of security profile identifiers (names and ARNs).

Type: Array of SecurityProfileIdentifier (p. 1059) 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++

519
 AWS IoT API Reference
ListSecurityProfiles

• AWS SDK for Go

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

520
 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. 521)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 521)

The token for the next set of results.

recursive (p. 521)

If true, return child groups too.

securityProfileTargetArn (p. 521)

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"
}
}
]

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

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

A list of security profiles and their associated targets.

Type: Array of SecurityProfileTargetMapping (p. 1061) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

522
 AWS IoT API Reference
ListSecurityProfilesForTarget

• AWS SDK for Ruby V3

523
 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. 524)

Set to true to return the list of streams in ascending order.

maxResults (p. 524)

The maximum number of results to return at a time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 524)

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.

524
 AWS IoT API Reference
ListStreams

nextToken (p. 524)

A token used to get the next set of results.

Type: String
streams (p. 524)

A list of streams.

Type: Array of StreamSummary (p. 1076) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

525
 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. 526)

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

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

The token to use to get the next set of results, or null if there are no additional results.

Type: String

526
 AWS IoT API Reference
ListTagsForResource

tags (p. 526)

The list of tags assigned to the resource.

Type: Array of Tag (p. 1077) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

527
 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. 528)

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

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

policyName (p. 528)

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.

528
 AWS IoT API Reference
ListTargetsForPolicy

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

nextMarker (p. 528)

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

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:

529
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

530
 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. 531)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 531)

The token for the next set of results.

securityProfileName (p. 531)

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.

531
 AWS IoT API Reference
ListTargetsForSecurityProfile

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

nextToken (p. 531)

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

The thing groups to which the security profile is attached.

Type: Array of SecurityProfileTarget (p. 1060) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

532
 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. 533)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

namePrefixFilter (p. 533)

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

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

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

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",

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

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

The thing groups.

Type: Array of GroupNameAndArn (p. 949) 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++

534
 AWS IoT API Reference
ListThingGroups

• AWS SDK for Go

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

535
 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. 536)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 536)

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

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.

536
 AWS IoT API Reference
ListThingGroupsForThing

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

nextToken (p. 536)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
thingGroups (p. 536)

The thing groups.

Type: Array of GroupNameAndArn (p. 949) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

537
 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. 538)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 538)

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

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.

538
 AWS IoT API Reference
ListThingPrincipals

nextToken (p. 538)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
principals (p. 538)

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 V3
• AWS SDK for PHP V3

539
 AWS IoT API Reference
ListThingPrincipals

• AWS SDK for Python

• AWS SDK for Ruby V3

540
 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. 541)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 541)

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

The type of task report.

Valid Values: ERRORS | RESULTS

Required: Yes
taskId (p. 541)

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.

541
 AWS IoT API Reference
ListThingRegistrationTaskReports

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

nextToken (p. 541)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
reportType (p. 541)

The type of task report.

Type: String

Valid Values: ERRORS | RESULTS

resourceLinks (p. 541)

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 V3

542
 AWS IoT API Reference
ListThingRegistrationTaskReports

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

543
 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. 544)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 544)

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

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

The token to use to get the next set of results, or null if there are no additional results.

544
 AWS IoT API Reference
ListThingRegistrationTasks

Type: String
taskIds (p. 544)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

545
 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. For more information, see List Things
from the AWS IoT Core Developer Guide.

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

The attribute name used to search for things.

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_.,@/:#-]+
attributeValue (p. 546)

The attribute value used to search for things.

Length Constraints: Maximum length of 800.

Pattern: [a-zA-Z0-9_.,@/:#-]*
maxResults (p. 546)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 546)

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

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:_-]+

546
 AWS IoT API Reference
ListThings

usePrefixAttributeValue (p. 546)

When true, the action returns the thing resources with attribute values that start with the
attributeValue provided.

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

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

The things.

Type: Array of ThingAttribute (p. 1082) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

547
 AWS IoT API Reference
ListThings

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

548
 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. 549)

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

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 549)

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.

549
 AWS IoT API Reference
ListThingsInBillingGroup

nextToken (p. 549)

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

550
 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. 551)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 551)

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

When true, list things in this thing group and in all child groups as well.
thingGroupName (p. 551)

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.

551
 AWS IoT API Reference
ListThingsInThingGroup

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

nextToken (p. 551)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
things (p. 551)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

552
 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. 553)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 553)

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

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"

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

The token for the next set of results. Will not be returned if operation has returned all results.

Type: String
thingTypes (p. 553)

The thing types.

Type: Array of ThingTypeDefinition (p. 1094) 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

554
 AWS IoT API Reference
ListThingTypes

• AWS SDK for C++

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

555
 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. 556)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 1000.

nextToken (p. 556)

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"
}

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

Information about a topic rule destination.

Type: Array of TopicRuleDestinationSummary (p. 1109) objects

nextToken (p. 556)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

557
 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. 558)

The maximum number of results to return.

Valid Range: Minimum value of 1. Maximum value of 10000.

nextToken (p. 558)

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

Specifies whether the rule is disabled.

topic (p. 558)

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"
}
]
}

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

The token to use to get the next set of results, or null if there are no additional results.

Type: String
rules (p. 558)

The rules.

Type: Array of TopicRuleListItem (p. 1111) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

559
 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. 560)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 560)

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

The type of resource for which you are configuring logging. Must be THING_Group.

Valid Values: DEFAULT | THING_GROUP | CLIENT_ID | SOURCE_IP | PRINCIPAL_ID |

EVENT_TYPE | DEVICE_DEFENDER

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.

560
 AWS IoT API Reference
ListV2LoggingLevels

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

logTargetConfigurations (p. 560)

The logging configuration for a target.

Type: Array of LogTargetConfiguration (p. 996) objects

nextToken (p. 560)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

561
 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. 562)

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

endTime (p. 562)

The end time for the alerts to be listed.

Required: Yes
listSuppressedAlerts (p. 562)

A list of all suppressed alerts.

maxResults (p. 562)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 562)

The token for the next set of results.

securityProfileName (p. 562)

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

The start time for the alerts to be listed.

Required: Yes
thingName (p. 562)

A filter to limit results to those alerts caused by the specified thing.

562
 AWS IoT API Reference
ListViolationEvents

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

verificationState (p. 562)

The verification state of the violation (detect alarm).

Valid Values: FALSE_POSITIVE | BENIGN_POSITIVE | TRUE_POSITIVE | UNKNOWN

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" ]
}
},
"exportMetric": boolean,
"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",
"verificationState": "string",
"verificationStateDescription": "string",

563
 AWS IoT API Reference
ListViolationEvents

"violationEventAdditionalInfo": {
"confidenceLevel": "string"
},
"violationEventTime": number,
"violationEventType": "string",
"violationId": "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. 563)

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

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. 1121) 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 V3

564
 AWS IoT API Reference
ListViolationEvents

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

565
 AWS IoT API Reference
PutVerificationStateOnViolation

PutVerificationStateOnViolation
Service: AWS IoT

Set a verification state and provide a description of that verification state on a violation (detect alarm).

Request Syntax
POST /violations/verification-state/violationId HTTP/1.1
Content-type: application/json

{
"verificationState": "string",
"verificationStateDescription": "string"
}

URI Request Parameters

The request uses the following URI parameters.

violationId (p. 566)

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

verificationState (p. 566)

The verification state of the violation.

Type: String

Valid Values: FALSE_POSITIVE | BENIGN_POSITIVE | TRUE_POSITIVE | UNKNOWN

Required: Yes
verificationStateDescription (p. 566)

The description of the verification state of the violation (detect alarm).

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [^\p{Cntrl}]*

Required: No

Response Syntax
HTTP/1.1 200

566
 AWS IoT API Reference
PutVerificationStateOnViolation

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

567
 AWS IoT API Reference
RegisterCACertificate

RegisterCACertificate
Service: AWS IoT

Registers a CA certificate with AWS IoT Core. There is no limit to the number of CA certificates you can
register in your AWS account. You can register up to 10 CA certificates with the same CA subject
field per AWS account.

Requires permission to access the RegisterCACertificate action.

Request Syntax
POST /cacertificate?allowAutoRegistration=allowAutoRegistration&setAsActive=setAsActive
HTTP/1.1
Content-type: application/json

{
"caCertificate": "string",
"certificateMode": "string",
"registrationConfig": {
"roleArn": "string",
"templateBody": "string",
"templateName": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"
}
],
"verificationCertificate": "string"
}

URI Request Parameters

The request uses the following URI parameters.

allowAutoRegistration (p. 568)

Allows this CA certificate to be used for auto registration of device certificates.

setAsActive (p. 568)

A boolean value that specifies if the CA certificate is set to active.

Valid values: ACTIVE | INACTIVE

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

caCertificate (p. 568)

The CA certificate.

Type: String

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

Pattern: [\s\S]*

568
 AWS IoT API Reference
RegisterCACertificate

Required: Yes
certificateMode (p. 568)

Describes the certificate mode in which the Certificate Authority (CA) will be registered. If the
verificationCertificate field is not provided, set certificateMode to be SNI_ONLY.
If the verificationCertificate field is provided, set certificateMode to be DEFAULT.
When certificateMode is not provided, it defaults to DEFAULT. All the device certificates that
are registered using this CA will be registered in the same certificate mode as the CA. For more
information about certificate mode for device certificates, see certificate mode.

Type: String

Valid Values: DEFAULT | SNI_ONLY

Required: No
registrationConfig (p. 568)

Information about the registration configuration.

Type: RegistrationConfig (p. 1041) object

Required: No
tags (p. 568)

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. 1077) objects

Required: No
verificationCertificate (p. 568)

The private key verification certificate. If certificateMode is SNI_ONLY, the

verificationCertificate field must be empty. If certificateMode is DEFAULT or not
provided, the verificationCertificate field must not be empty.

Type: String

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

Pattern: [\s\S]*

Required: No

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

{
"certificateArn": "string",
"certificateId": "string"
}

569
 AWS IoT API Reference
RegisterCACertificate

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

The CA certificate ARN.

Type: String
certificateId (p. 569)

The CA certificate identifier.

Type: String

Length Constraints: Fixed length of 64.

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

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

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

570
 AWS IoT API Reference
RegisterCACertificate

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

571
 AWS IoT API Reference
RegisterCertificate

RegisterCertificate
Service: AWS IoT

Registers a device certificate with AWS IoT in the same certificate mode as the signing CA. 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. 572)

This parameter has been deprecated.

A boolean value that specifies if the certificate is set to active.

Valid values: ACTIVE | INACTIVE

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

caCertificatePem (p. 572)

The CA certificate used to sign the device certificate being registered.

Type: String

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

Pattern: [\s\S]*

Required: No
certificatePem (p. 572)

The certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*

Required: Yes

572
 AWS IoT API Reference
RegisterCertificate

status (p. 572)

The status of the register certificate request. Valid values that you can use include ACTIVE,
INACTIVE, and REVOKED.

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.

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

certificateArn (p. 573)

The certificate ARN.

Type: String
certificateId (p. 573)

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

573
 AWS IoT API Reference
RegisterCertificate

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.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

574
 AWS IoT API Reference
RegisterCertificateWithoutCA

RegisterCertificateWithoutCA
Service: AWS IoT

Register a certificate that does not have a certificate authority (CA). For supported certificates, consult
Certificate signing algorithms supported by AWS IoT.

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

The certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*

Required: Yes
status (p. 575)

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"
}

575
 AWS IoT API Reference
RegisterCertificateWithoutCA

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

The Amazon Resource Name (ARN) of the registered certificate.

Type: String
certificateId (p. 575)

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

576
 AWS IoT API Reference
RegisterCertificateWithoutCA

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

577
 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. 578)

The parameters for provisioning a thing. See Provisioning Templates for more information.

Type: String to string map

Key Length Constraints: Minimum length of 0. Maximum length of 2048.

Key Pattern: [\s\S]*

Value Length Constraints: Minimum length of 0. Maximum length of 4096.

Value Pattern: [\s\S]*

Required: No
templateBody (p. 578)

The provisioning template. See Provisioning Devices That Have Device Certificates for more
information.

Type: String

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

Pattern: [\s\S]*

Required: Yes

578
 AWS IoT API Reference
RegisterThing

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

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

certificatePem (p. 579)

The certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*
resourceArns (p. 579)

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

579
 AWS IoT API Reference
RegisterThing

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

580
 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. 440) 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. 581)

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

The reason the certificate transfer was rejected.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\s\S]*

Required: No

Response Syntax
HTTP/1.1 200

581
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

582
 AWS IoT API Reference
RejectCertificateTransfer

• AWS SDK for Ruby V3

583
 AWS IoT API Reference
RemoveThingFromBillingGroup

RemoveThingFromBillingGroup
Service: AWS IoT

Removes the given thing from the billing group.

Requires permission to access the RemoveThingFromBillingGroup action.

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

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

The ARN of the billing group.

Type: String

Required: No
billingGroupName (p. 584)

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

The ARN of the thing to be removed from the billing group.

Type: String

Required: No
thingName (p. 584)

The name of the thing to be removed from the billing group.

584
 AWS IoT API Reference
RemoveThingFromBillingGroup

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

585
 AWS IoT API Reference
RemoveThingFromBillingGroup

586
 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. 587)

The ARN of the thing to remove from the group.

Type: String

Required: No
thingGroupArn (p. 587)

The group ARN.

Type: String

Required: No
thingGroupName (p. 587)

The group name.

Type: String

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

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

Required: No
thingName (p. 587)

The name of the thing to remove from the group.

587
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

588
 AWS IoT API Reference
RemoveThingFromThingGroup

589
 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

{
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"batchMode": boolean,
"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,

590
 AWS IoT API Reference
ReplaceTopicRule

"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",
"headers": [
{

591
 AWS IoT API Reference
ReplaceTopicRule

"key": "string",
"value": "string"
}
],
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"location": {
"deviceId": "string",
"latitude": "string",
"longitude": "string",
"roleArn": "string",
"timestamp": {
"unit": "string",
"value": "string"
},
"trackerName": "string"
},
"openSearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"republish": {
"headers": {
"contentType": "string",
"correlationData": "string",
"messageExpiry": "string",
"payloadFormatIndicator": "string",
"responseTopic": "string",
"userProperties": [
{
"key": "string",
"value": "string"
}
]
},
"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"

592
 AWS IoT API Reference
ReplaceTopicRule

},
"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"
},
"cloudwatchLogs": {
"batchMode": boolean,
"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"
},

593
 AWS IoT API Reference
ReplaceTopicRule

"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": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]

594
 AWS IoT API Reference
ReplaceTopicRule

}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"headers": [
{
"key": "string",
"value": "string"
}
],
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"location": {
"deviceId": "string",
"latitude": "string",
"longitude": "string",
"roleArn": "string",
"timestamp": {
"unit": "string",
"value": "string"
},
"trackerName": "string"
},
"openSearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"republish": {
"headers": {
"contentType": "string",
"correlationData": "string",
"messageExpiry": "string",
"payloadFormatIndicator": "string",
"responseTopic": "string",
"userProperties": [
{
"key": "string",
"value": "string"
}
]
},
"qos": number,
"roleArn": "string",
"topic": "string"
},
"s3": {
"bucketName": "string",
"cannedAcl": "string",

595
 AWS IoT API Reference
ReplaceTopicRule

"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,
"sql": "string"
}

URI Request Parameters

The request uses the following URI parameters.

ruleName (p. 590)

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.

actions (p. 590)

The actions associated with the rule.

596
 AWS IoT API Reference
ReplaceTopicRule

Type: Array of Action (p. 853) objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: Yes
awsIotSqlVersion (p. 590)

The version of the SQL rules engine to use when evaluating the rule.

Type: String

Required: No
description (p. 590)

The description of the rule.

Type: String

Required: No
errorAction (p. 590)

The action to take when an error occurs.

Type: Action (p. 853) object

Required: No
ruleDisabled (p. 590)

Specifies whether the rule is disabled.

Type: Boolean

Required: No
sql (p. 590)

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

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.

597
 AWS IoT API Reference
ReplaceTopicRule

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

598
 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. 599)

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

The maximum number of results to return per page at one time. The response might contain fewer
results but will never contain more.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 500.

Required: No
nextToken (p. 599)

The token used to get the next set of results, or null if there are no additional results.

Type: String

Required: No

599
 AWS IoT API Reference
SearchIndex

queryString (p. 599)

The search query string. For more information about the search query syntax, see Query syntax.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 599)

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
},
"deviceDefender": "string",
"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.

600
 AWS IoT API Reference
SearchIndex

nextToken (p. 600)

The token used to get the next set of results, or null if there are no additional results.

Type: String
thingGroups (p. 600)

The thing groups that match the search query.

Type: Array of ThingGroupDocument (p. 1087) objects

things (p. 600)

The things that match the search query.

Type: Array of ThingDocument (p. 1085) 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

601
 AWS IoT API Reference
SearchIndex

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

602
 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. 603)

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

The authorizer ARN.

603
 AWS IoT API Reference
SetDefaultAuthorizer

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 603)

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

604
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

605
 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. 499) 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. 606)

The policy name.

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

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

Required: Yes
policyVersionId (p. 606)

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

606
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

607
 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

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

logLevel (p. 608)

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
roleArn (p. 608)

The ARN of the IAM role that grants access.

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
InternalException

An unexpected error has occurred.

608
 AWS IoT API Reference
SetLoggingOptions

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

609
 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. 610)

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: Yes
logTarget (p. 610)

The log target.

Type: LogTarget (p. 995) 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.

610
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

611
 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. 612)

The default logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
disableAllLogs (p. 612)

If true all logs are disabled. The default is false.

Type: Boolean

Required: No
roleArn (p. 612)

The ARN of the role that allows IoT to write to Cloudwatch logs.

Type: String

Required: No

Response Syntax
HTTP/1.1 200

612
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

613
 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. 614)

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

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_-]+

614
 AWS IoT API Reference
StartAuditMitigationActionsTask

Required: Yes
clientRequestToken (p. 614)

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

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. 875) 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. 615)

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

615
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

616
 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. 617)

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

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

617
 AWS IoT API Reference
StartDetectMitigationActionsTask

clientRequestToken (p. 617)

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

Specifies to list only active violations.

Type: Boolean

Required: No
includeSuppressedAlerts (p. 617)

Specifies to include suppressed alerts.

Type: Boolean

Required: No
target (p. 617)

Specifies the ML Detect findings to which the mitigation actions are applied.

Type: DetectMitigationActionsTaskTarget (p. 930) object

Required: Yes
violationEventOccurrenceRange (p. 617)

Specifies the time period of which violation events occurred between.

Type: ViolationEventOccurrenceRange (p. 1124) 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.

618
 AWS IoT API Reference
StartDetectMitigationActionsTask

taskId (p. 618)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

619
 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. 620)

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

The ID of the on-demand audit you started.

Type: String

620
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

621
 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. 622)

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

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

The IAM role ARN that grants permission the input file.

Type: String

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

622
 AWS IoT API Reference
StartThingRegistrationTask

Required: Yes
templateBody (p. 622)

The provisioning template.

Type: String

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

Pattern: [\s\S]*

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

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.

623
 AWS IoT API Reference
StartThingRegistrationTask

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

624
 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. 625)

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

625
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

626
 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. 627)

The ARN of the resource.

Type: String

Required: Yes
tags (p. 627)

The new or modified tags for the resource.

Type: Array of Tag (p. 1077) 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.

627
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

628
 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. 629)

The MQTT client ID.

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

authInfos (p. 629)

A list of authorization info objects. Simulating authorization will create a response for each
authInfo object in the list.

Type: Array of AuthInfo (p. 880) objects

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

Required: Yes
cognitoIdentityPoolId (p. 629)

The Cognito identity pool ID.

Type: String

Required: No
policyNamesToAdd (p. 629)

When testing custom authorization, the policies specified here are treated as if they are attached to
the principal being authorized.

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

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

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": [
{

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

The authentication results.

Type: Array of AuthResult (p. 885) 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.

631
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

632
 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. 633)

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

Specifies a test HTTP authorization request.

Type: HttpContext (p. 954) object

Required: No

633
 AWS IoT API Reference
TestInvokeAuthorizer

mqttContext (p. 633)

Specifies a test MQTT authorization request.

Type: MqttContext (p. 1011) object

Required: No
tlsContext (p. 633)

Specifies a test TLS authorization request.

Type: TlsContext (p. 1103) object

Required: No
token (p. 633)

The token returned by your custom authentication service.

Type: String

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

Pattern: [\s\S]*

Required: No
tokenSignature (p. 633)

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

The number of seconds after which the connection is terminated.

634
 AWS IoT API Reference
TestInvokeAuthorizer

Type: Integer
isAuthenticated (p. 634)

True if the token is authenticated, otherwise false.

Type: Boolean
policyDocuments (p. 634)

IAM policy documents.

Type: Array of strings

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

Pattern: [\s\S]*
principalId (p. 634)

The principal ID.

Type: String

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

Pattern: [a-zA-Z0-9]+
refreshAfterInSeconds (p. 634)

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

635
 AWS IoT API Reference
TestInvokeAuthorizer

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

636
 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. 658) action to deactivate it.

The certificate must not have any policies attached to it. You can use the DetachPolicy (p. 339) 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. 637)

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

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

The transfer message.

637
 AWS IoT API Reference
TransferCertificate

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\s\S]*

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

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

638
 AWS IoT API Reference
TransferCertificate

ThrottlingException

The rate exceeds the limit.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

639
 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. 640)

The ARN of the resource.

Type: String

Required: Yes
tagKeys (p. 640)

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.

640
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

641
 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. 642)

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. 867) object map

Required: No
auditNotificationTargetConfigurations (p. 642)

Information about the targets to which audit notifications are sent.

642
 AWS IoT API Reference
UpdateAccountAuditConfiguration

Type: String to AuditNotificationTarget (p. 876) object map

Valid Keys: SNS

Required: No
roleArn (p. 642)

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 V3
• AWS SDK for PHP V3

643
 AWS IoT API Reference
UpdateAccountAuditConfiguration

• AWS SDK for Python

• AWS SDK for Ruby V3

644
 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",
"deviceCertificateArn": "string",
"deviceCertificateId": "string",
"iamRoleArn": "string",
"issuerCertificateIdentifier": {
"issuerCertificateSerialNumber": "string",
"issuerCertificateSubject": "string",
"issuerId": "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. 645)

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

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

645
 AWS IoT API Reference
UpdateAuditSuppression

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

Required: No
expirationDate (p. 645)

The expiration date (epoch timestamp in seconds) that you want the suppression to adhere to.

Type: Timestamp

Required: No
resourceIdentifier (p. 645)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 1045) object

Required: Yes
suppressIndefinitely (p. 645)

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

646
 AWS IoT API Reference
UpdateAuditSuppression

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

647
 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",
"enableCachingForHttp": boolean,
"status": "string",
"tokenKeyName": "string",
"tokenSigningPublicKeys": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

authorizerName (p. 648)

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

The ARN of the authorizer's Lambda function.

Type: String

Length Constraints: Maximum length of 2048.

Pattern: [\s\S]*

Required: No
enableCachingForHttp (p. 648)

When true, the result from the authorizer’s Lambda function is cached for the time specified
in refreshAfterInSeconds. The cached result is used while the device reuses the same HTTP
connection.

Type: Boolean

648
 AWS IoT API Reference
UpdateAuthorizer

Required: No
status (p. 648)

The status of the update authorizer request.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
tokenKeyName (p. 648)

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

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.

Value Pattern: [\s\S]*

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

The authorizer ARN.

Type: String

649
 AWS IoT API Reference
UpdateAuthorizer

Length Constraints: Maximum length of 2048.

authorizerName (p. 649)

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

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

650
 AWS IoT API Reference
UpdateAuthorizer

• AWS SDK for Go

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

651
 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. 652)

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

The properties of the billing group.

Type: BillingGroupProperties (p. 901) object

Required: Yes
expectedVersion (p. 652)

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

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

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

653
 AWS IoT API Reference
UpdateBillingGroup

• AWS SDK for Java V2

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

654
 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",
"templateName": "string"
},
"removeAutoRegistration": boolean
}

URI Request Parameters

The request uses the following URI parameters.

caCertificateId (p. 655)

The CA certificate identifier.

Length Constraints: Fixed length of 64.

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

Required: Yes
newAutoRegistrationStatus (p. 655)

The new value for the auto registration status. Valid values are: "ENABLE" or "DISABLE".

Valid Values: ENABLE | DISABLE

newStatus (p. 655)

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

Information about the registration configuration.

Type: RegistrationConfig (p. 1041) object

655
 AWS IoT API Reference
UpdateCACertificate

Required: No
removeAutoRegistration (p. 655)

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

656
 AWS IoT API Reference
UpdateCACertificate

• AWS SDK for .NET

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

657
 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. 658)

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

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

658
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

659
 AWS IoT API Reference
UpdateCertificate

• AWS SDK for Ruby V3

660
 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. 661)

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

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

661
 AWS IoT API Reference
UpdateCustomMetric

"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. 661)

The creation date of the custom metric in milliseconds since epoch.

Type: Timestamp
displayName (p. 661)

A friendly name in the console for the custom metric

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Graph}\x20]*
lastModifiedDate (p. 661)

The time the custom metric was last modified in milliseconds since epoch.

Type: Timestamp
metricArn (p. 661)

The Amazon Resource Number (ARN) of the custom metric.

Type: String
metricName (p. 661)

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

The type of the custom metric.

Important
The type number only takes a single metric value as an input, but while submitting the
metrics value in the DeviceMetrics report, it must be passed as an array with a single value.

Type: String

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

Errors
InternalFailureException

An unexpected error has occurred.

662
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

663
 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. 664)

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

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 100 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,

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

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

Type: String
creationDate (p. 664)

The date and time, in milliseconds since epoch, when the dimension was initially created.

Type: Timestamp
lastModifiedDate (p. 664)

The date and time, in milliseconds since epoch, when the dimension was most recently updated.

Type: Timestamp
name (p. 664)

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

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

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

type (p. 664)

The type of the dimension.

Type: String

Valid Values: TOPIC_FILTER

Errors
InternalFailureException

An unexpected error has occurred.

665
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

666
 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,
"tlsConfig": {
"securityPolicy": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 667)

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

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 881) object

Required: No
domainConfigurationStatus (p. 667)

The status to which the domain configuration should be updated.

Type: String

Valid Values: ENABLED | DISABLED

667
 AWS IoT API Reference
UpdateDomainConfiguration

Required: No
removeAuthorizerConfig (p. 667)

Removes the authorization configuration from a domain.

Type: Boolean

Required: No
tlsConfig (p. 667)

An object that specifies the TLS configuration for a domain.

Type: TlsConfig (p. 1102) object

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

The ARN of the domain configuration that was updated.

Type: String
domainConfigurationName (p. 668)

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.

668
 AWS IoT API Reference
UpdateDomainConfiguration

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

669
 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. 670)

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

The expected version of the dynamic thing group to update.

Type: Long

Required: No
indexName (p. 670)

The dynamic thing group index to update.

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

The dynamic thing group search query string to update.

Type: String

Length Constraints: Minimum length of 1.

Required: No
queryVersion (p. 670)

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

The dynamic thing group properties to update.

Type: ThingGroupProperties (p. 1091) 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. 671)

The dynamic thing group version.

Type: Long

671
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

672
 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. 673)

The new event configuration values.

Type: String to Configuration (p. 921) 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

673
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

674
 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. 675)

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

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
aggregationType (p. 675)

The type of the aggregation query.

Type: AggregationType (p. 860) object

675
 AWS IoT API Reference
UpdateFleetMetric

Required: No
description (p. 675)

The description of the fleet metric.

Type: String

Length Constraints: Maximum length of 1024.

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

Required: No
expectedVersion (p. 675)

The expected version of the fleet metric record in the registry.

Type: Long

Required: No
indexName (p. 675)

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

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

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: No
queryVersion (p. 675)

The version of the query.

Type: String

Required: No
unit (p. 675)

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

676
 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

677
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

678
 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"
}
],
"deviceDefenderIndexingMode": "string",
"filter": {
"geoLocations": [
{
"name": "string",
"order": "string"
}
],
"namedShadowNames": [ "string" ]
},
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"namedShadowIndexingMode": "string",
"thingConnectivityIndexingMode": "string",
"thingIndexingMode": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

679
 AWS IoT API Reference
UpdateIndexingConfiguration

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

thingGroupIndexingConfiguration (p. 679)

Thing group indexing configuration.

Type: ThingGroupIndexingConfiguration (p. 1089) object

Required: No
thingIndexingConfiguration (p. 679)

Thing indexing configuration.

Type: ThingIndexingConfiguration (p. 1092) 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

680
 AWS IoT API Reference
UpdateIndexingConfiguration

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

681
 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",
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
},
"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. 682)

The ID of the job to be updated.

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

682
 AWS IoT API Reference
UpdateJob

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

Required: Yes
namespaceId (p. 682)

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.

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

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

abortConfig (p. 682)

Allows you to create criteria to abort a job.

Type: AbortConfig (p. 850) object

Required: No
description (p. 682)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
jobExecutionsRetryConfig (p. 682)

Allows you to create the criteria to retry a job.

Type: JobExecutionsRetryConfig (p. 972) object

Required: No
jobExecutionsRolloutConfig (p. 682)

Allows you to create a staged rollout of the job.

Type: JobExecutionsRolloutConfig (p. 973) object

Required: No
presignedUrlConfig (p. 682)

Configuration information for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 1031) object

Required: No

683
 AWS IoT API Reference
UpdateJob

timeoutConfig (p. 682)

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. 1097) 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
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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

684
 AWS IoT API Reference
UpdateJob

• AWS SDK for Ruby V3

685
 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. 686)

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.

686
 AWS IoT API Reference
UpdateMitigationAction

actionParams (p. 686)

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

Type: MitigationActionParams (p. 1009) object

Required: No
roleArn (p. 686)

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

The ARN for the new mitigation action.

Type: String
actionId (p. 687)

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

687
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

688
 AWS IoT API Reference
UpdatePackage

UpdatePackage
Service: AWS IoT

Updates the supported fields for a specific software package.

Requires permission to access the UpdatePackage and GetIndexingConfiguration actions.

Request Syntax
PATCH /packages/packageName?clientToken=clientToken HTTP/1.1
Content-type: application/json

{
"defaultVersionName": "string",
"description": "string",
"unsetDefaultVersion": boolean
}

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 689)

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 36. Maximum length of 64.

Pattern: \S{36,64}
packageName (p. 689)

The name of the target software package.

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.

defaultVersionName (p. 689)

The name of the default package version.

Note: You cannot name a defaultVersion and set unsetDefaultVersion equal to true at the
same time.

Type: String

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

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

Required: No

689
 AWS IoT API Reference
UpdatePackage

description (p. 689)

The package description.

Type: String

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

Pattern: [^\p{C}]+

Required: No
unsetDefaultVersion (p. 689)

Indicates whether you want to remove the named default package version from the software
package. Set as true to remove the default package version.

Note: You cannot name a defaultVersion and set unsetDefaultVersion equal to true at the
same time.

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
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

HTTP Status Code: 400

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

690
 AWS IoT API Reference
UpdatePackage

• 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

691
 AWS IoT API Reference
UpdatePackageConfiguration

UpdatePackageConfiguration
Service: AWS IoT

Updates the software package configuration.

Requires permission to access the UpdatePackageConfiguration and iam:PassRole actions.

Request Syntax
PATCH /package-configuration?clientToken=clientToken HTTP/1.1
Content-type: application/json

{
"versionUpdateByJobsConfig": {
"enabled": boolean,
"roleArn": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 692)

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 36. Maximum length of 64.

Pattern: \S{36,64}

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

versionUpdateByJobsConfig (p. 692)

Configuration to manage job's package version reporting. This updates the thing's reserved named
shadow that the job targets.

Type: VersionUpdateByJobsConfig (p. 1120) 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.

692
 AWS IoT API Reference
UpdatePackageConfiguration

Errors
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

693
 AWS IoT API Reference
UpdatePackageVersion

UpdatePackageVersion
Service: AWS IoT

Updates the supported fields for a specific package version.

Requires permission to access the UpdatePackageVersion and GetIndexingConfiguration actions.

Request Syntax
PATCH /packages/packageName/versions/versionName?clientToken=clientToken HTTP/1.1
Content-type: application/json

{
"action": "string",
"attributes": {
"string" : "string"
},
"description": "string"
}

URI Request Parameters

The request uses the following URI parameters.

clientToken (p. 694)

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 36. Maximum length of 64.

Pattern: \S{36,64}
packageName (p. 694)

The name of the associated software package.

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

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

Required: Yes
versionName (p. 694)

The name of the target package version.

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.

action (p. 694)

The status that the package version should be assigned. For more information, see Package version
lifecycle.

694
 AWS IoT API Reference
UpdatePackageVersion

Type: String

Valid Values: PUBLISH | DEPRECATE

Required: No
attributes (p. 694)

Metadata that can be used to define a package version’s configuration. For example, the Amazon S3
file location, configuration options that are being sent to the device or fleet.

Note: Attributes can be updated only when the package version is in a draft state.

The combined size of all the attributes on a package version is limited to 3KB.

Type: String to string map

Key Length Constraints: Minimum length of 1.

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

Value Length Constraints: Minimum length of 1.

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

Required: No
description (p. 694)

The package version description.

Type: String

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

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
InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

695
 AWS IoT API Reference
UpdatePackageVersion

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

ValidationException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

696
 AWS IoT API Reference
UpdateProvisioningTemplate

UpdateProvisioningTemplate
Service: AWS IoT

Updates a 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. 697)

The name of the 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. 697)

The ID of the default provisioning template version.

Type: Integer

Required: No
description (p. 697)

The description of the provisioning template.

Type: String

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

Pattern: [^\p{C}]*

697
 AWS IoT API Reference
UpdateProvisioningTemplate

Required: No
enabled (p. 697)

True to enable the provisioning template, otherwise false.

Type: Boolean

Required: No
preProvisioningHook (p. 697)

Updates the pre-provisioning hook template. Only supports template of type

FLEET_PROVISIONING. For more information about provisioning template types, see type.

Type: ProvisioningHook (p. 1032) object

Required: No
provisioningRoleArn (p. 697)

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

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

698
 AWS IoT API Reference
UpdateProvisioningTemplate

InvalidRequestException

The request is not valid.

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

699
 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. 700)

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

The number of seconds the credential will be valid.

This value must be less than or equal to the maximum session duration of the IAM role that the role
alias references.

Type: Integer

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

Required: No
roleArn (p. 700)

The role ARN.

Type: String

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

Required: No

700
 AWS IoT API Reference
UpdateRoleAlias

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

The role alias.

Type: String

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

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

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.

701
 AWS IoT API Reference
UpdateRoleAlias

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

702
 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. 703)

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

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

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

703
 AWS IoT API Reference
UpdateScheduledAudit

Required: No
frequency (p. 703)

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

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

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.

704
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

705
 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": [
{
"exportMetric": boolean,
"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" ]
}
},
"exportMetric": boolean,
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"deleteAdditionalMetricsToRetain": boolean,

706
 AWS IoT API Reference
UpdateSecurityProfile

"deleteAlertTargets": boolean,
"deleteBehaviors": boolean,
"deleteMetricsExportConfig": boolean,
"metricsExportConfig": {
"mqttTopic": "string",
"roleArn": "string"
},
"securityProfileDescription": "string"
}

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 706)

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

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

This parameter has been deprecated.

Please use UpdateSecurityProfile:additionalMetricsToRetainV2 (p. 707) 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. 706)

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. 1004) objects

Required: No
alertTargets (p. 706)

Where the alerts are sent. (Alerts are always sent to the console.)

707
 AWS IoT API Reference
UpdateSecurityProfile

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

Valid Keys: SNS

Required: No
behaviors (p. 706)

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

Type: Array of Behavior (p. 894) objects

Array Members: Maximum number of 100 items.

Required: No
deleteAdditionalMetricsToRetain (p. 706)

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

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

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
deleteMetricsExportConfig (p. 706)

Set the value as true to delete metrics export related configurations.

Type: Boolean

Required: No
metricsExportConfig (p. 706)

Specifies the MQTT topic and role ARN required for metric export.

Type: MetricsExportConfig (p. 1003) object

Required: No
securityProfileDescription (p. 706)

A description of the security profile.

Type: String

708
 AWS IoT API Reference
UpdateSecurityProfile

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": [
{
"exportMetric": boolean,
"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" ]
}
},
"exportMetric": boolean,
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"creationDate": number,
"lastModifiedDate": number,

709
 AWS IoT API Reference
UpdateSecurityProfile

"metricsExportConfig": {
"mqttTopic": "string",
"roleArn": "string"
},
"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. 709)

This parameter has been deprecated.

Please use UpdateSecurityProfile:additionalMetricsToRetainV2 (p. 710) 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

additionalMetricsToRetainV2 (p. 709)

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. 1004) objects

alertTargets (p. 709)

Where the alerts are sent. (Alerts are always sent to the console.)

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

Valid Keys: SNS

behaviors (p. 709)

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

Type: Array of Behavior (p. 894) objects

Array Members: Maximum number of 100 items.

creationDate (p. 709)

The time the security profile was created.

Type: Timestamp
lastModifiedDate (p. 709)

The time the security profile was last modified.

Type: Timestamp
metricsExportConfig (p. 709)

Specifies the MQTT topic and role ARN required for metric export.

710
 AWS IoT API Reference
UpdateSecurityProfile

Type: MetricsExportConfig (p. 1003) object

securityProfileArn (p. 709)

The ARN of the security profile that was updated.

Type: String
securityProfileDescription (p. 709)

The description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*
securityProfileName (p. 709)

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

The updated version of the security profile.

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

711
 AWS IoT API Reference
UpdateSecurityProfile

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

712
 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. 713)

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

The description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 713)

The files associated with the stream.

713
 AWS IoT API Reference
UpdateStream

Type: Array of StreamFile (p. 1073) objects

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

Required: No
roleArn (p. 713)

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

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
streamArn (p. 714)

The stream ARN.

Type: String
streamId (p. 714)

The stream ID.

Type: String

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

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

The stream version.

714
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

715
 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. 716)

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

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. 866) object

Required: No

716
 AWS IoT API Reference
UpdateThing

expectedVersion (p. 716)

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

Remove a thing type association. If true, the association is removed.

Type: Boolean

Required: No
thingTypeName (p. 716)

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.

717
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

718
 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. 719)

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

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

The thing group properties.

Type: ThingGroupProperties (p. 1091) object

Required: Yes

719
 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. 720)

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

720
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

721
 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. 722)

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

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

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

722
 AWS IoT API Reference
UpdateThingGroupsForThing

thingName (p. 722)

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 V3
• AWS SDK for PHP V3

723
 AWS IoT API Reference
UpdateThingGroupsForThing

• AWS SDK for Python

• AWS SDK for Ruby V3

724
 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. 725)

The ARN of the topic rule destination.

Type: String

Required: Yes
status (p. 725)

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.

725
 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 V3

726
 AWS IoT API Reference
UpdateTopicRuleDestination

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

727
 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" ]
}
},
"exportMetric": boolean,
"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. 728)

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

Type: Array of Behavior (p. 894) objects

728
 AWS IoT API Reference
ValidateSecurityProfileBehaviors

Array Members: Maximum number of 100 items.

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

True if the behaviors were valid.

Type: Boolean
validationErrors (p. 729)

The list of any errors found in the behaviors.

Type: Array of ValidationError (p. 1119) 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:

729
 AWS IoT API Reference
AWS IoT 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 V3
• 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. 731)

• GetRetainedMessage (p. 734)
• GetThingShadow (p. 737)
• ListNamedShadowsForThing (p. 740)
• ListRetainedMessages (p. 743)
• Publish (p. 746)
• UpdateThingShadow (p. 749)

730
 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. 731)

The name of the shadow.

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

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

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

The state information, in JSON format.

731
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

732
 AWS IoT API Reference
DeleteThingShadow

• AWS SDK for Ruby V3

733
 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. 734)

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

The Epoch date and time, in milliseconds, when the retained message was stored by AWS IoT.

Type: Long
payload (p. 734)

The Base64-encoded message payload of the retained message body.

734
 AWS IoT API Reference
GetRetainedMessage

Type: Base64-encoded binary data object

qos (p. 734)

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

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

735
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

736
 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. 737)

The name of the shadow.

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

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

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

The state information, in JSON format.

737
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

738
 AWS IoT API Reference
GetThingShadow

• AWS SDK for Ruby V3

739
 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. 740)

The token to retrieve the next set of results.

pageSize (p. 740)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 100.

thingName (p. 740)

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.

740
 AWS IoT API Reference
ListNamedShadowsForThing

nextToken (p. 740)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
results (p. 740)

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

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

741
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

742
 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. 743)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 200.

nextToken (p. 743)

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.

743
 AWS IoT API Reference
ListRetainedMessages

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

nextToken (p. 743)

The token for the next set of results, or null if there are no additional results.

Type: String
retainedTopics (p. 743)

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

744
 AWS IoT API Reference
ListRetainedMessages

• AWS SDK for JavaScript V3

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

745
 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?
contentType=contentType&messageExpiry=messageExpiry&qos=qos&responseTopic=responseTopic&retain=retain
HTTP/1.1
x-amz-mqtt5-user-properties: userProperties
x-amz-mqtt5-payload-format-indicator: payloadFormatIndicator
x-amz-mqtt5-correlation-data: correlationData

payload

URI Request Parameters

The request uses the following URI parameters.

contentType (p. 746)

A UTF-8 encoded string that describes the content of the publishing message.
correlationData (p. 746)

The base64-encoded binary data used by the sender of the request message to identify which
request the response message is for when it's received. correlationData is an HTTP header value
in the API.
messageExpiry (p. 746)

A user-defined integer value that represents the message expiry interval in seconds. If absent, the
message doesn't expire. For more information about the limits of messageExpiry, see AWS IoT
Core message broker and protocol limits and quotas from the AWS Reference Guide.
payloadFormatIndicator (p. 746)

An Enum string value that indicates whether the payload is formatted as UTF-8.
payloadFormatIndicator is an HTTP header value in the API.

Valid Values: UNSPECIFIED_BYTES | UTF8_DATA

qos (p. 746)

The Quality of Service (QoS) level. The default QoS level is 0.

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

responseTopic (p. 746)

A UTF-8 encoded string that's used as the topic name for a response message. The response topic is
used to describe the topic which the receiver should publish to as part of the request-response flow.
The topic must not contain wildcard characters.

746
 AWS IoT API Reference
Publish

retain (p. 746)

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

The name of the MQTT topic.

Required: Yes
userProperties (p. 746)

A JSON string that contains an array of JSON objects. If you don’t use AWS SDK or AWS CLI,
you must encode the JSON string to base64 format before adding it to the HTTP header.
userProperties is an HTTP header value in the API.

The following example userProperties parameter is a JSON string which represents two User
Properties. Note that it needs to be base64-encoded:

[{"deviceName": "alpha"}, {"deviceCnt": "45"}]

Request Body
The request accepts the following binary data.

payload (p. 746)

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

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

747
 AWS IoT API Reference
Publish

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

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
• AWS SDK for JavaScript V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

748
 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. 749)

The name of the shadow.

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

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

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

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.

749
 AWS IoT API Reference
UpdateThingShadow

The response returns the following as the HTTP body.

payload (p. 749)

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:

750
 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 V3
• 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. 752)

• GetPendingJobExecutions (p. 755)
• StartNextPendingJobExecution (p. 758)
• UpdateJobExecution (p. 761)

751
 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. 752)

Optional. A number that identifies a particular job execution on a particular device. If not specified,
the latest job execution is returned.
includeJobDocument (p. 752)

Optional. Unless set to false, the response contains the job document. The default is true.
jobId (p. 752)

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

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.

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

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

752
 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. 753)

Contains data about a job execution.

Type: JobExecution (p. 1130) 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.

753
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

754
 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. 755)

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.

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

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,
"versionNumber": number

755
 AWS IoT API Reference
GetPendingJobExecutions

}
],
"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. 755)

A list of JobExecutionSummary objects with status IN_PROGRESS.

Type: Array of JobExecutionSummary (p. 1134) objects

queuedJobs (p. 755)

A list of JobExecutionSummary objects with status QUEUED.

Type: Array of JobExecutionSummary (p. 1134) 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

756
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

757
 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. 758)

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.

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

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

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.

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

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

A JobExecution object.

Type: JobExecution (p. 1130) object

759
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

760
 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. 761)

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

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.

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

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

761
 AWS IoT API Reference
UpdateJobExecution

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

executionNumber (p. 761)

Optional. A number that identifies a particular job execution on a particular device.

Type: Long

Required: No
expectedVersion (p. 761)

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

Optional. When set to true, the response contains the job document. The default is false.

Type: Boolean

Required: No
includeJobExecutionState (p. 761)

Optional. When included and set to true, the response contains the JobExecutionState data. The
default is false.

Type: Boolean

Required: No
status (p. 761)

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

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

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

762
 AWS IoT API Reference
UpdateJobExecution

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

Value Length Constraints: Minimum length of 1.

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

Required: No
stepTimeoutInMinutes (p. 761)

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

A JobExecutionState object.

Type: JobExecutionState (p. 1133) object

jobDocument (p. 763)

The contents of the Job Documents.

Type: String

Length Constraints: Maximum length of 32768.

763
 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 V3
• 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:

764
 AWS IoT API Reference
AWS IoT Core Device Advisor

• CreateSuiteDefinition (p. 766)

• DeleteSuiteDefinition (p. 769)
• GetEndpoint (p. 771)
• GetSuiteDefinition (p. 773)
• GetSuiteRun (p. 776)
• GetSuiteRunReport (p. 780)
• ListSuiteDefinitions (p. 782)
• ListSuiteRuns (p. 784)
• ListTagsForResource (p. 787)
• StartSuiteRun (p. 789)
• StopSuiteRun (p. 792)
• TagResource (p. 794)
• UntagResource (p. 796)
• UpdateSuiteDefinition (p. 798)

765
 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",
"deviceRoleArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"isLongDurationTest": boolean,
"protocol": "string",
"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. 766)

Creates a Device Advisor test suite with suite definition configuration.

Type: SuiteDefinitionConfiguration (p. 1138) object

Required: Yes
tags (p. 766)

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.

766
 AWS IoT API Reference
CreateSuiteDefinition

Required: No

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

The timestamp of when the test suite was created.

Type: Timestamp
suiteDefinitionArn (p. 767)

The Amazon Resource Name (ARN) of the test suite.

Type: String

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

suiteDefinitionId (p. 767)

The UUID of the test suite created.

Type: String

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

suiteDefinitionName (p. 767)

The suite definition name of the test suite. This is a required parameter.

Type: String

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

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ValidationException

Sends a validation exception.

767
 AWS IoT API Reference
CreateSuiteDefinition

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

768
 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. 769)

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 an Internal Failure exception.

HTTP Status Code: 500

ValidationException

Sends a validation 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

769
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

770
 AWS IoT API Reference
GetEndpoint

GetEndpoint
Service: AWS IoT Core Device Advisor

Gets information about an Device Advisor endpoint.

Request Syntax
GET /endpoint?
authenticationMethod=authenticationMethod&certificateArn=certificateArn&deviceRoleArn=deviceRoleArn&thi
HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

authenticationMethod (p. 771)

The authentication method used during the device connection.

Valid Values: X509ClientCertificate | SignatureVersion4

certificateArn (p. 771)

The certificate ARN of the device. This is an optional parameter.

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

deviceRoleArn (p. 771)

The device role ARN of the device. This is an optional parameter.

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

thingArn (p. 771)

The thing ARN of the device. This is an optional parameter.

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

Request Body
The request does not have a request body.

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

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

771
 AWS IoT API Reference
GetEndpoint

endpoint (p. 771)

The response of an Device Advisor endpoint.

Type: String

Length Constraints: Minimum length of 45. Maximum length of 75.

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

772
 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. 773)

Suite definition ID of the test suite to get.

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

Required: Yes
suiteDefinitionVersion (p. 773)

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",
"deviceRoleArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"isLongDurationTest": boolean,
"protocol": "string",
"rootGroup": "string",
"suiteDefinitionName": "string"

773
 AWS IoT API Reference
GetSuiteDefinition

},
"suiteDefinitionId": "string",
"suiteDefinitionVersion": "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.

createdAt (p. 773)

Date (in Unix epoch time) when the suite definition was created.

Type: Timestamp
lastModifiedAt (p. 773)

Date (in Unix epoch time) when the suite definition was last modified.

Type: Timestamp
latestVersion (p. 773)

Latest suite definition version of the suite definition.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

suiteDefinitionArn (p. 773)

The ARN of the suite definition.

Type: String

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

suiteDefinitionConfiguration (p. 773)

Suite configuration of the suite definition.

Type: SuiteDefinitionConfiguration (p. 1138) object

suiteDefinitionId (p. 773)

Suite definition ID of the suite definition.

Type: String

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

suiteDefinitionVersion (p. 773)

Suite definition version of the suite definition.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

tags (p. 773)

Tags attached to the suite definition.

774
 AWS IoT API Reference
GetSuiteDefinition

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.

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

775
 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. 776)

Suite definition ID for the test suite run.

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

Required: Yes
suiteRunId (p. 776)

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": {
"parallelRun": boolean,
"primaryDevice": {
"certificateArn": "string",
"deviceRoleArn": "string",
"thingArn": "string"
},
"selectedTestList": [ "string" ]
},

776
 AWS IoT API Reference
GetSuiteRun

"suiteRunId": "string",
"tags": {
"string" : "string"
},
"testResult": {
"groups": [
{
"groupId": "string",
"groupName": "string",
"tests": [
{
"endTime": number,
"failure": "string",
"logUrl": "string",
"startTime": number,
"status": "string",
"testCaseDefinitionId": "string",
"testCaseDefinitionName": "string",
"testCaseRunId": "string",
"testScenarios": [
{
"failure": "string",
"status": "string",
"systemMessage": "string",
"testCaseScenarioId": "string",
"testCaseScenarioType": "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. 776)

Date (in Unix epoch time) when the test suite run ended.

Type: Timestamp
errorReason (p. 776)

Error reason for any test suite run failure.

Type: String
startTime (p. 776)

Date (in Unix epoch time) when the test suite run started.

Type: Timestamp
status (p. 776)

Status for the test suite run.

Type: String

777
 AWS IoT API Reference
GetSuiteRun

Valid Values: PASS | FAIL | CANCELED | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR
suiteDefinitionId (p. 776)

Suite definition ID for the test suite run.

Type: String

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

suiteDefinitionVersion (p. 776)

Suite definition version for the test suite run.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

suiteRunArn (p. 776)

The ARN of the suite run.

Type: String

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

suiteRunConfiguration (p. 776)

Suite run configuration for the test suite run.

Type: SuiteRunConfiguration (p. 1142) object

suiteRunId (p. 776)

Suite run ID for the test suite run.

Type: String

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

tags (p. 776)

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

Test results for the test suite run.

Type: TestResult (p. 1149) object

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

778
 AWS IoT API Reference
GetSuiteRun

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

779
 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. 780)

Suite definition ID of the test suite.

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

Required: Yes
suiteRunId (p. 780)

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

Download URL of the qualification report.

Type: String

780
 AWS IoT API Reference
GetSuiteRunReport

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

781
 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. 782)

The maximum number of results to return at once.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken (p. 782)

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",
"deviceRoleArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"isLongDurationTest": boolean,
"protocol": "string",
"suiteDefinitionId": "string",
"suiteDefinitionName": "string"
}
]
}

782
 AWS IoT API Reference
ListSuiteDefinitions

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

A token used to get the next set of results.

Type: String

Length Constraints: Maximum length of 2000.

suiteDefinitionInformationList (p. 782)

An array of objects that provide summaries of information about the suite definitions in the list.

Type: Array of SuiteDefinitionInformation (p. 1140) objects

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

783
 AWS IoT API Reference
ListSuiteRuns

ListSuiteRuns
Service: AWS IoT Core Device Advisor

Lists 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. 784)

The maximum number of results to return at once.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken (p. 784)

A token to retrieve the next set of results.

Length Constraints: Maximum length of 2000.

suiteDefinitionId (p. 784)

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

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,

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

A token to retrieve the next set of results.

Type: String

Length Constraints: Maximum length of 2000.

suiteRunsList (p. 784)

An array of objects that provide summaries of information about the suite runs in the list.

Type: Array of SuiteRunInformation (p. 1143) objects

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

785
 AWS IoT API Reference
ListSuiteRuns

• AWS SDK for Ruby V3

786
 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. 787)

The resource ARN of the IoT Device Advisor resource. This can be SuiteDefinition ARN or SuiteRun
ARN.

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

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.

787
 AWS IoT API Reference
ListTagsForResource

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

788
 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": {
"parallelRun": boolean,
"primaryDevice": {
"certificateArn": "string",
"deviceRoleArn": "string",
"thingArn": "string"
},
"selectedTestList": [ "string" ]
},
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 789)

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

Suite definition version of the test suite.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

Required: No
suiteRunConfiguration (p. 789)

Suite run configuration.

Type: SuiteRunConfiguration (p. 1142) object

789
 AWS IoT API Reference
StartSuiteRun

Required: Yes
tags (p. 789)

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,
"endpoint": "string",
"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. 790)

Starts a Device Advisor test suite run based on suite create time.

Type: Timestamp
endpoint (p. 790)

The response of an Device Advisor test endpoint.

Type: String

Length Constraints: Minimum length of 45. Maximum length of 75.

suiteRunArn (p. 790)

Amazon Resource Name (ARN) of the started suite run.

Type: String

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

suiteRunId (p. 790)

Suite Run ID of the started suite run.

Type: String

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

790
 AWS IoT API Reference
StartSuiteRun

Errors
ConflictException

Sends a Conflict Exception.

HTTP Status Code: 400

InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

791
 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. 792)

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

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 an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

792
 AWS IoT API Reference
StopSuiteRun

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

793
 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. 794)

The resource ARN of an IoT Device Advisor resource. This can be SuiteDefinition ARN or SuiteRun
ARN.

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

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.

794
 AWS IoT API Reference
TagResource

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

795
 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. 796)

The resource ARN of an IoT Device Advisor resource. This can be SuiteDefinition ARN or SuiteRun
ARN.

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

Required: Yes
tagKeys (p. 796)

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 an Internal Failure exception.

HTTP Status Code: 500

ResourceNotFoundException

Sends a Resource Not Found exception.

796
 AWS IoT API Reference
UntagResource

HTTP Status Code: 404

ValidationException

Sends a validation 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

797
 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",
"deviceRoleArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"isLongDurationTest": boolean,
"protocol": "string",
"rootGroup": "string",
"suiteDefinitionName": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 798)

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

Updates a Device Advisor test suite with suite definition configuration.

Type: SuiteDefinitionConfiguration (p. 1138) object

Required: Yes

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

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

Timestamp of when the test suite was created.

Type: Timestamp
lastUpdatedAt (p. 798)

Timestamp of when the test suite was updated.

Type: Timestamp
suiteDefinitionArn (p. 798)

Amazon Resource Name (ARN) of the updated test suite.

Type: String

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

suiteDefinitionId (p. 798)

Suite definition ID of the updated test suite.

Type: String

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

suiteDefinitionName (p. 798)

Updates the suite definition name. This is a required parameter.

Type: String

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

suiteDefinitionVersion (p. 798)

Suite definition version of the updated test suite.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

Errors
InternalServerException

Sends an Internal Failure exception.

799
 AWS IoT API Reference
AWS IoT Fleet Hub

HTTP Status Code: 500

ValidationException

Sends a validation 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 V3
• 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. 801)

• DeleteApplication (p. 804)
• DescribeApplication (p. 806)
• ListApplications (p. 810)
• ListTagsForResource (p. 812)
• TagResource (p. 814)
• UntagResource (p. 816)
• UpdateApplication (p. 818)

800
 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. 801)

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No
applicationName (p. 801)

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: Yes
clientToken (p. 801)

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.

801
 AWS IoT API Reference
CreateApplication

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

Required: No
roleArn (p. 801)

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

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 0. 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. 802)

The ARN of the web application.

Type: String

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

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

802
 AWS IoT API Reference
CreateApplication

applicationId (p. 802)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

803
 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. 804)

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

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.

804
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

805
 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. 806)

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.

806
 AWS IoT API Reference
DescribeApplication

applicationArn (p. 806)

The ARN of the web application.

Type: String

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

Pattern: ^arn:[!-~]+$
applicationCreationDate (p. 806)

The date (in Unix epoch time) when the application was created.

Type: Long
applicationDescription (p. 806)

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$
applicationId (p. 806)

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

The date (in Unix epoch time) when the application was last updated.

Type: Long
applicationName (p. 806)

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$
applicationState (p. 806)

The current state of the web application.

Type: String

Valid Values: CREATING | DELETING | ACTIVE | CREATE_FAILED | DELETE_FAILED

applicationUrl (p. 806)

The URL of the web application.

Type: String

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

807
 AWS IoT API Reference
DescribeApplication

Pattern: ^https\://\S+$
errorMessage (p. 806)

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

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

The Id of the single sign-on client that you use to authenticate and authorize users on the web
application.

Type: String
tags (p. 806)

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

808
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

809
 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. 810)

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

An array of objects that provide summaries of information about the web applications in the list.

Type: Array of ApplicationSummary (p. 1150) objects

810
 AWS IoT API Reference
ListApplications

nextToken (p. 810)

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

811
 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. 812)

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

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 0. Maximum length of 256.

812
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

813
 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. 814)

The ARN of the resource.

Required: Yes

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

tags (p. 814)

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

814
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

815
 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. 816)

The ARN of the resource.

Required: Yes
tagKeys (p. 816)

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

816
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

817
 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. 818)

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

An optional description of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No
applicationName (p. 818)

The name of the web application.

Type: String

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

Pattern: ^[ -~]*$

Required: No

818
 AWS IoT API Reference
UpdateApplication

clientToken (p. 818)

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

819
 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 V3
• 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. 821)

• DescribeTunnel (p. 823)
• ListTagsForResource (p. 825)
• ListTunnels (p. 827)
• OpenTunnel (p. 829)
• RotateTunnelAccessToken (p. 832)
• TagResource (p. 835)
• UntagResource (p. 837)

820
 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. 1160).

The request accepts the following data in JSON format.

delete (p. 821)

When set to true, AWS IoT Secure Tunneling deletes the tunnel data immediately.

Type: Boolean

Required: No
tunnelId (p. 821)

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:

821
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

822
 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. 1160).

The request accepts the following data in JSON format.

tunnelId (p. 823)

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

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

The tunnel being described.

Type: Tunnel (p. 1156) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

824
 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. 1160).

The request accepts the following data in JSON format.

resourceArn (p. 825)

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

The tags for the specified resource.

Type: Array of Tag (p. 1154) objects

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

825
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

826
 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. 1160).

The request accepts the following data in JSON format.

maxResults (p. 827)

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

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

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
{

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

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

A short description of the tunnels in an AWS account.

Type: Array of TunnelSummary (p. 1158) 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

828
 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. 1160).

The request accepts the following data in JSON format.

description (p. 829)

A short text description of the tunnel.

Type: String

Pattern: [^\p{C}]{1,2048}

Required: No
destinationConfig (p. 829)

The destination configuration for the OpenTunnel request.

Type: DestinationConfig (p. 1153) object

Required: No
tags (p. 829)

A collection of tag metadata.

Type: Array of Tag (p. 1154) objects

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

Required: No

829
 AWS IoT API Reference
OpenTunnel

timeoutConfig (p. 829)

Timeout configuration for a tunnel.

Type: TimeoutConfig (p. 1155) 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. 830)

The access token the destination local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
sourceAccessToken (p. 830)

The access token the source local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
tunnelArn (p. 830)

The Amazon Resource Name for the tunnel.

Type: String

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

tunnelId (p. 830)

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

830
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

831
 AWS IoT API Reference
RotateTunnelAccessToken

RotateTunnelAccessToken
Service: AWS IoT Secure Tunneling

Revokes the current client access token (CAT) and returns new CAT for clients to use when reconnecting
to secure tunneling to access the same tunnel.

Requires permission to access the RotateTunnelAccessToken action.

Note
Rotating the CAT doesn't extend the tunnel duration. For example, say the tunnel duration is 12
hours and the tunnel has already been open for 4 hours. When you rotate the access tokens, the
new tokens that are generated can only be used for the remaining 8 hours.

Request Syntax
{
"clientMode": "string",
"destinationConfig": {
"services": [ "string" ],
"thingName": "string"
},
"tunnelId": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 1160).

The request accepts the following data in JSON format.

clientMode (p. 832)

The mode of the client that will use the client token, which can be either the source or destination,
or both source and destination.

Type: String

Valid Values: SOURCE | DESTINATION | ALL

Required: Yes
destinationConfig (p. 832)

The destination configuration.

Type: DestinationConfig (p. 1153) object

Required: No
tunnelId (p. 832)

The tunnel for which you want to rotate the access tokens.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Required: Yes

832
 AWS IoT API Reference
RotateTunnelAccessToken

Response Syntax
{
"destinationAccessToken": "string",
"sourceAccessToken": "string",
"tunnelArn": "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. 833)

The client access token that the destination local proxy uses to connect to AWS IoT Secure
Tunneling.

Type: String
sourceAccessToken (p. 833)

The client access token that the source local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
tunnelArn (p. 833)

The Amazon Resource Name for the tunnel.

Type: String

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

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 V3
• AWS SDK for PHP V3
• AWS SDK for Python

833
 AWS IoT API Reference
RotateTunnelAccessToken

• AWS SDK for Ruby V3

834
 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. 1160).

The request accepts the following data in JSON format.

resourceArn (p. 835)

The ARN of the resource.

Type: String

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

Required: Yes
tags (p. 835)

The tags for the resource.

Type: Array of Tag (p. 1154) 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

835
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

836
 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. 1160).

The request accepts the following data in JSON format.

resourceArn (p. 837)

The resource ARN.

Type: String

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

Required: Yes
tagKeys (p. 837)

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:

837
 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 V3
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

838
 AWS IoT API Reference

Data Types
The following data types are supported by AWS IoT:

• AbortConfig (p. 850)

• AbortCriteria (p. 851)
• Action (p. 853)
• ActiveViolation (p. 857)
• AddThingsToThingGroupParams (p. 859)
• AggregationType (p. 860)
• AlertTarget (p. 861)
• Allowed (p. 862)
• AssetPropertyTimestamp (p. 863)
• AssetPropertyValue (p. 864)
• AssetPropertyVariant (p. 865)
• AttributePayload (p. 866)
• AuditCheckConfiguration (p. 867)
• AuditCheckDetails (p. 868)
• AuditFinding (p. 870)
• AuditMitigationActionExecutionMetadata (p. 872)
• AuditMitigationActionsTaskMetadata (p. 874)
• AuditMitigationActionsTaskTarget (p. 875)
• AuditNotificationTarget (p. 876)
• AuditSuppression (p. 877)
• AuditTaskMetadata (p. 879)
• AuthInfo (p. 880)
• AuthorizerConfig (p. 881)
• AuthorizerDescription (p. 882)
• AuthorizerSummary (p. 884)
• AuthResult (p. 885)
• AwsJobAbortConfig (p. 886)
• AwsJobAbortCriteria (p. 887)
• AwsJobExecutionsRolloutConfig (p. 889)
• AwsJobExponentialRolloutRate (p. 890)
• AwsJobPresignedUrlConfig (p. 891)
• AwsJobRateIncreaseCriteria (p. 892)
• AwsJobTimeoutConfig (p. 893)
• Behavior (p. 894)
• BehaviorCriteria (p. 896)
• BehaviorModelTrainingSummary (p. 898)
• BillingGroupMetadata (p. 900)
• BillingGroupProperties (p. 901)
• Bucket (p. 902)
• BucketsAggregationType (p. 903)

839
 AWS IoT API Reference

• CACertificate (p. 904)

• CACertificateDescription (p. 905)
• Certificate (p. 908)
• CertificateDescription (p. 910)
• CertificateValidity (p. 913)
• CloudwatchAlarmAction (p. 914)
• CloudwatchLogsAction (p. 915)
• CloudwatchMetricAction (p. 916)
• CodeSigning (p. 918)
• CodeSigningCertificateChain (p. 919)
• CodeSigningSignature (p. 920)
• Configuration (p. 921)
• CustomCodeSigning (p. 922)
• Denied (p. 923)
• Destination (p. 924)
• DetectMitigationActionExecution (p. 925)
• DetectMitigationActionsTaskStatistics (p. 927)
• DetectMitigationActionsTaskSummary (p. 928)
• DetectMitigationActionsTaskTarget (p. 930)
• DocumentParameter (p. 931)
• DomainConfigurationSummary (p. 933)
• DynamoDBAction (p. 934)
• DynamoDBv2Action (p. 936)
• EffectivePolicy (p. 937)
• ElasticsearchAction (p. 938)
• EnableIoTLoggingParams (p. 940)
• ErrorInfo (p. 941)
• ExplicitDeny (p. 942)
• ExponentialRolloutRate (p. 943)
• Field (p. 944)
• FileLocation (p. 945)
• FirehoseAction (p. 946)
• FleetMetricNameAndArn (p. 947)
• GeoLocationTarget (p. 948)
• GroupNameAndArn (p. 949)
• HttpAction (p. 950)
• HttpActionHeader (p. 952)
• HttpAuthorization (p. 953)
• HttpContext (p. 954)
• HttpUrlDestinationConfiguration (p. 955)
• HttpUrlDestinationProperties (p. 956)
• HttpUrlDestinationSummary (p. 957)
• ImplicitDeny (p. 958)
• IndexingFilter (p. 959)
• IotAnalyticsAction (p. 960)
• IotEventsAction (p. 961)

840
 AWS IoT API Reference

• IotSiteWiseAction (p. 963)

• IssuerCertificateIdentifier (p. 964)
• Job (p. 965)
• JobExecution (p. 970)
• JobExecutionsRetryConfig (p. 972)
• JobExecutionsRolloutConfig (p. 973)
• JobExecutionStatusDetails (p. 974)
• JobExecutionSummary (p. 975)
• JobExecutionSummaryForJob (p. 977)
• JobExecutionSummaryForThing (p. 978)
• JobProcessDetails (p. 979)
• JobSummary (p. 981)
• JobTemplateSummary (p. 983)
• KafkaAction (p. 985)
• KafkaActionHeader (p. 987)
• KeyPair (p. 988)
• KinesisAction (p. 989)
• LambdaAction (p. 990)
• LocationAction (p. 991)
• LocationTimestamp (p. 993)
• LoggingOptionsPayload (p. 994)
• LogTarget (p. 995)
• LogTargetConfiguration (p. 996)
• MachineLearningDetectionConfig (p. 997)
• MaintenanceWindow (p. 998)
• ManagedJobTemplateSummary (p. 999)
• MetricDatum (p. 1001)
• MetricDimension (p. 1002)
• MetricsExportConfig (p. 1003)
• MetricToRetain (p. 1004)
• MetricValue (p. 1005)
• MitigationAction (p. 1007)
• MitigationActionIdentifier (p. 1008)
• MitigationActionParams (p. 1009)
• MqttContext (p. 1011)
• MqttHeaders (p. 1012)
• NonCompliantResource (p. 1014)
• OpenSearchAction (p. 1015)
• OTAUpdateFile (p. 1016)
• OTAUpdateInfo (p. 1018)
• OTAUpdateSummary (p. 1021)
• OutgoingCertificate (p. 1022)
• PackageSummary (p. 1024)
• PackageVersionSummary (p. 1025)
• PercentPair (p. 1027)
• Policy (p. 1028)

841
 AWS IoT API Reference

• PolicyVersion (p. 1029)

• PolicyVersionIdentifier (p. 1030)
• PresignedUrlConfig (p. 1031)
• ProvisioningHook (p. 1032)
• ProvisioningTemplateSummary (p. 1033)
• ProvisioningTemplateVersionSummary (p. 1035)
• PublishFindingToSnsParams (p. 1036)
• PutAssetPropertyValueEntry (p. 1037)
• PutItemInput (p. 1039)
• RateIncreaseCriteria (p. 1040)
• RegistrationConfig (p. 1041)
• RelatedResource (p. 1042)
• ReplaceDefaultPolicyVersionParams (p. 1043)
• RepublishAction (p. 1044)
• ResourceIdentifier (p. 1045)
• RetryCriteria (p. 1047)
• RoleAliasDescription (p. 1048)
• S3Action (p. 1050)
• S3Destination (p. 1051)
• S3Location (p. 1052)
• SalesforceAction (p. 1053)
• ScheduledAuditMetadata (p. 1054)
• ScheduledJobRollout (p. 1056)
• SchedulingConfig (p. 1057)
• SecurityProfileIdentifier (p. 1059)
• SecurityProfileTarget (p. 1060)
• SecurityProfileTargetMapping (p. 1061)
• ServerCertificateSummary (p. 1062)
• SigningProfileParameter (p. 1063)
• SigV4Authorization (p. 1064)
• SnsAction (p. 1065)
• SqsAction (p. 1066)
• StartSigningJobParameter (p. 1067)
• StatisticalThreshold (p. 1068)
• Statistics (p. 1069)
• StepFunctionsAction (p. 1071)
• Stream (p. 1072)
• StreamFile (p. 1073)
• StreamInfo (p. 1074)
• StreamSummary (p. 1076)
• Tag (p. 1077)
• TaskStatistics (p. 1078)
• TaskStatisticsForAuditCheck (p. 1080)
• TermsAggregation (p. 1081)
• ThingAttribute (p. 1082)
• ThingConnectivity (p. 1084)

842
 AWS IoT API Reference

• ThingDocument (p. 1085)

• ThingGroupDocument (p. 1087)
• ThingGroupIndexingConfiguration (p. 1089)
• ThingGroupMetadata (p. 1090)
• ThingGroupProperties (p. 1091)
• ThingIndexingConfiguration (p. 1092)
• ThingTypeDefinition (p. 1094)
• ThingTypeMetadata (p. 1095)
• ThingTypeProperties (p. 1096)
• TimeoutConfig (p. 1097)
• TimestreamAction (p. 1098)
• TimestreamDimension (p. 1100)
• TimestreamTimestamp (p. 1101)
• TlsConfig (p. 1102)
• TlsContext (p. 1103)
• TopicRule (p. 1104)
• TopicRuleDestination (p. 1106)
• TopicRuleDestinationConfiguration (p. 1108)
• TopicRuleDestinationSummary (p. 1109)
• TopicRuleListItem (p. 1111)
• TopicRulePayload (p. 1112)
• TransferData (p. 1114)
• UpdateCACertificateParams (p. 1116)
• UpdateDeviceCertificateParams (p. 1117)
• UserProperty (p. 1118)
• ValidationError (p. 1119)
• VersionUpdateByJobsConfig (p. 1120)
• ViolationEvent (p. 1121)
• ViolationEventAdditionalInfo (p. 1123)
• ViolationEventOccurrenceRange (p. 1124)
• VpcDestinationConfiguration (p. 1125)
• VpcDestinationProperties (p. 1126)
• VpcDestinationSummary (p. 1127)

The following data types are supported by AWS IoT data:

• RetainedMessageSummary (p. 1128)

The following data types are supported by AWS IoT jobs data:

• JobExecution (p. 1130)

• JobExecutionState (p. 1133)
• JobExecutionSummary (p. 1134)

The following data types are supported by AWS IoT Core Device Advisor:

• DeviceUnderTest (p. 1136)

843
 AWS IoT API Reference
AWS IoT

• GroupResult (p. 1137)

• SuiteDefinitionConfiguration (p. 1138)
• SuiteDefinitionInformation (p. 1140)
• SuiteRunConfiguration (p. 1142)
• SuiteRunInformation (p. 1143)
• TestCaseRun (p. 1145)
• TestCaseScenario (p. 1147)
• TestResult (p. 1149)

The following data types are supported by AWS IoT Fleet Hub:

• ApplicationSummary (p. 1150)

The following data types are supported by AWS IoT Secure Tunneling:

• ConnectionState (p. 1152)

• DestinationConfig (p. 1153)
• Tag (p. 1154)
• TimeoutConfig (p. 1155)
• Tunnel (p. 1156)
• TunnelSummary (p. 1158)

AWS IoT
The following data types are supported by AWS IoT:

• AbortConfig (p. 850)

• AbortCriteria (p. 851)
• Action (p. 853)
• ActiveViolation (p. 857)
• AddThingsToThingGroupParams (p. 859)
• AggregationType (p. 860)
• AlertTarget (p. 861)
• Allowed (p. 862)
• AssetPropertyTimestamp (p. 863)
• AssetPropertyValue (p. 864)
• AssetPropertyVariant (p. 865)
• AttributePayload (p. 866)
• AuditCheckConfiguration (p. 867)
• AuditCheckDetails (p. 868)
• AuditFinding (p. 870)
• AuditMitigationActionExecutionMetadata (p. 872)
• AuditMitigationActionsTaskMetadata (p. 874)
• AuditMitigationActionsTaskTarget (p. 875)
• AuditNotificationTarget (p. 876)
• AuditSuppression (p. 877)

844
 AWS IoT API Reference
AWS IoT

• AuditTaskMetadata (p. 879)

• AuthInfo (p. 880)
• AuthorizerConfig (p. 881)
• AuthorizerDescription (p. 882)
• AuthorizerSummary (p. 884)
• AuthResult (p. 885)
• AwsJobAbortConfig (p. 886)
• AwsJobAbortCriteria (p. 887)
• AwsJobExecutionsRolloutConfig (p. 889)
• AwsJobExponentialRolloutRate (p. 890)
• AwsJobPresignedUrlConfig (p. 891)
• AwsJobRateIncreaseCriteria (p. 892)
• AwsJobTimeoutConfig (p. 893)
• Behavior (p. 894)
• BehaviorCriteria (p. 896)
• BehaviorModelTrainingSummary (p. 898)
• BillingGroupMetadata (p. 900)
• BillingGroupProperties (p. 901)
• Bucket (p. 902)
• BucketsAggregationType (p. 903)
• CACertificate (p. 904)
• CACertificateDescription (p. 905)
• Certificate (p. 908)
• CertificateDescription (p. 910)
• CertificateValidity (p. 913)
• CloudwatchAlarmAction (p. 914)
• CloudwatchLogsAction (p. 915)
• CloudwatchMetricAction (p. 916)
• CodeSigning (p. 918)
• CodeSigningCertificateChain (p. 919)
• CodeSigningSignature (p. 920)
• Configuration (p. 921)
• CustomCodeSigning (p. 922)
• Denied (p. 923)
• Destination (p. 924)
• DetectMitigationActionExecution (p. 925)
• DetectMitigationActionsTaskStatistics (p. 927)
• DetectMitigationActionsTaskSummary (p. 928)
• DetectMitigationActionsTaskTarget (p. 930)
• DocumentParameter (p. 931)
• DomainConfigurationSummary (p. 933)
• DynamoDBAction (p. 934)
• DynamoDBv2Action (p. 936)
• EffectivePolicy (p. 937)
• ElasticsearchAction (p. 938)
• EnableIoTLoggingParams (p. 940)

845
 AWS IoT API Reference
AWS IoT

• ErrorInfo (p. 941)

• ExplicitDeny (p. 942)
• ExponentialRolloutRate (p. 943)
• Field (p. 944)
• FileLocation (p. 945)
• FirehoseAction (p. 946)
• FleetMetricNameAndArn (p. 947)
• GeoLocationTarget (p. 948)
• GroupNameAndArn (p. 949)
• HttpAction (p. 950)
• HttpActionHeader (p. 952)
• HttpAuthorization (p. 953)
• HttpContext (p. 954)
• HttpUrlDestinationConfiguration (p. 955)
• HttpUrlDestinationProperties (p. 956)
• HttpUrlDestinationSummary (p. 957)
• ImplicitDeny (p. 958)
• IndexingFilter (p. 959)
• IotAnalyticsAction (p. 960)
• IotEventsAction (p. 961)
• IotSiteWiseAction (p. 963)
• IssuerCertificateIdentifier (p. 964)
• Job (p. 965)
• JobExecution (p. 970)
• JobExecutionsRetryConfig (p. 972)
• JobExecutionsRolloutConfig (p. 973)
• JobExecutionStatusDetails (p. 974)
• JobExecutionSummary (p. 975)
• JobExecutionSummaryForJob (p. 977)
• JobExecutionSummaryForThing (p. 978)
• JobProcessDetails (p. 979)
• JobSummary (p. 981)
• JobTemplateSummary (p. 983)
• KafkaAction (p. 985)
• KafkaActionHeader (p. 987)
• KeyPair (p. 988)
• KinesisAction (p. 989)
• LambdaAction (p. 990)
• LocationAction (p. 991)
• LocationTimestamp (p. 993)
• LoggingOptionsPayload (p. 994)
• LogTarget (p. 995)
• LogTargetConfiguration (p. 996)
• MachineLearningDetectionConfig (p. 997)
• MaintenanceWindow (p. 998)
• ManagedJobTemplateSummary (p. 999)

846
 AWS IoT API Reference
AWS IoT

• MetricDatum (p. 1001)

• MetricDimension (p. 1002)
• MetricsExportConfig (p. 1003)
• MetricToRetain (p. 1004)
• MetricValue (p. 1005)
• MitigationAction (p. 1007)
• MitigationActionIdentifier (p. 1008)
• MitigationActionParams (p. 1009)
• MqttContext (p. 1011)
• MqttHeaders (p. 1012)
• NonCompliantResource (p. 1014)
• OpenSearchAction (p. 1015)
• OTAUpdateFile (p. 1016)
• OTAUpdateInfo (p. 1018)
• OTAUpdateSummary (p. 1021)
• OutgoingCertificate (p. 1022)
• PackageSummary (p. 1024)
• PackageVersionSummary (p. 1025)
• PercentPair (p. 1027)
• Policy (p. 1028)
• PolicyVersion (p. 1029)
• PolicyVersionIdentifier (p. 1030)
• PresignedUrlConfig (p. 1031)
• ProvisioningHook (p. 1032)
• ProvisioningTemplateSummary (p. 1033)
• ProvisioningTemplateVersionSummary (p. 1035)
• PublishFindingToSnsParams (p. 1036)
• PutAssetPropertyValueEntry (p. 1037)
• PutItemInput (p. 1039)
• RateIncreaseCriteria (p. 1040)
• RegistrationConfig (p. 1041)
• RelatedResource (p. 1042)
• ReplaceDefaultPolicyVersionParams (p. 1043)
• RepublishAction (p. 1044)
• ResourceIdentifier (p. 1045)
• RetryCriteria (p. 1047)
• RoleAliasDescription (p. 1048)
• S3Action (p. 1050)
• S3Destination (p. 1051)
• S3Location (p. 1052)
• SalesforceAction (p. 1053)
• ScheduledAuditMetadata (p. 1054)
• ScheduledJobRollout (p. 1056)
• SchedulingConfig (p. 1057)
• SecurityProfileIdentifier (p. 1059)
• SecurityProfileTarget (p. 1060)

847
 AWS IoT API Reference
AWS IoT

• SecurityProfileTargetMapping (p. 1061)

• ServerCertificateSummary (p. 1062)
• SigningProfileParameter (p. 1063)
• SigV4Authorization (p. 1064)
• SnsAction (p. 1065)
• SqsAction (p. 1066)
• StartSigningJobParameter (p. 1067)
• StatisticalThreshold (p. 1068)
• Statistics (p. 1069)
• StepFunctionsAction (p. 1071)
• Stream (p. 1072)
• StreamFile (p. 1073)
• StreamInfo (p. 1074)
• StreamSummary (p. 1076)
• Tag (p. 1077)
• TaskStatistics (p. 1078)
• TaskStatisticsForAuditCheck (p. 1080)
• TermsAggregation (p. 1081)
• ThingAttribute (p. 1082)
• ThingConnectivity (p. 1084)
• ThingDocument (p. 1085)
• ThingGroupDocument (p. 1087)
• ThingGroupIndexingConfiguration (p. 1089)
• ThingGroupMetadata (p. 1090)
• ThingGroupProperties (p. 1091)
• ThingIndexingConfiguration (p. 1092)
• ThingTypeDefinition (p. 1094)
• ThingTypeMetadata (p. 1095)
• ThingTypeProperties (p. 1096)
• TimeoutConfig (p. 1097)
• TimestreamAction (p. 1098)
• TimestreamDimension (p. 1100)
• TimestreamTimestamp (p. 1101)
• TlsConfig (p. 1102)
• TlsContext (p. 1103)
• TopicRule (p. 1104)
• TopicRuleDestination (p. 1106)
• TopicRuleDestinationConfiguration (p. 1108)
• TopicRuleDestinationSummary (p. 1109)
• TopicRuleListItem (p. 1111)
• TopicRulePayload (p. 1112)
• TransferData (p. 1114)
• UpdateCACertificateParams (p. 1116)
• UpdateDeviceCertificateParams (p. 1117)
• UserProperty (p. 1118)
• ValidationError (p. 1119)

848
 AWS IoT API Reference
AWS IoT

• VersionUpdateByJobsConfig (p. 1120)

• ViolationEvent (p. 1121)
• ViolationEventAdditionalInfo (p. 1123)
• ViolationEventOccurrenceRange (p. 1124)
• VpcDestinationConfiguration (p. 1125)
• VpcDestinationProperties (p. 1126)
• VpcDestinationSummary (p. 1127)

849
 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. 851) 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

850
 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

851
AWS IoT API Reference
AbortCriteria

852
 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. 914) object

Required: No
cloudwatchLogs

Send data to CloudWatch Logs.

Type: CloudwatchLogsAction (p. 915) object

Required: No
cloudwatchMetric

Capture a CloudWatch metric.

Type: CloudwatchMetricAction (p. 916) object

Required: No
dynamoDB

Write to a DynamoDB table.

Type: DynamoDBAction (p. 934) 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. 936) object

Required: No
elasticsearch

Write data to an Amazon OpenSearch Service domain.

Note
The Elasticsearch action can only be used by existing rule actions. To create a new rule
action or to update an existing rule action, use the OpenSearch rule action instead. For
more information, see OpenSearchAction.

Type: ElasticsearchAction (p. 938) object

Required: No
firehose

Write to an Amazon Kinesis Firehose stream.

853
 AWS IoT API Reference
Action

Type: FirehoseAction (p. 946) object

Required: No
http

Send data to an HTTPS endpoint.

Type: HttpAction (p. 950) object

Required: No
iotAnalytics

Sends message data to an AWS IoT Analytics channel.

Type: IotAnalyticsAction (p. 960) object

Required: No
iotEvents

Sends an input to an AWS IoT Events detector.

Type: IotEventsAction (p. 961) object

Required: No
iotSiteWise

Sends data from the MQTT message that triggered the rule to AWS IoT SiteWise asset properties.

Type: IotSiteWiseAction (p. 963) 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. 985) object

Required: No
kinesis

Write data to an Amazon Kinesis stream.

Type: KinesisAction (p. 989) object

Required: No
lambda

Invoke a Lambda function.

Type: LambdaAction (p. 990) object

Required: No
location

The Amazon Location Service rule action sends device location updates from an MQTT message to
an Amazon Location tracker resource.

Type: LocationAction (p. 991) object

854
 AWS IoT API Reference
Action

Required: No
openSearch

Write data to an Amazon OpenSearch Service domain.

Type: OpenSearchAction (p. 1015) object

Required: No
republish

Publish to another MQTT topic.

Type: RepublishAction (p. 1044) object

Required: No
s3

Write to an Amazon S3 bucket.

Type: S3Action (p. 1050) object

Required: No
salesforce

Send a message to a Salesforce IoT Cloud Input Stream.

Type: SalesforceAction (p. 1053) object

Required: No
sns

Publish to an Amazon SNS topic.

Type: SnsAction (p. 1065) object

Required: No
sqs

Publish to an Amazon SQS queue.

Type: SqsAction (p. 1066) object

Required: No
stepFunctions

Starts execution of a Step Functions state machine.

Type: StepFunctionsAction (p. 1071) 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. 1098) object

Required: No

855
 AWS IoT API Reference
Action

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
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. 894) 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. 1005) 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
verificationState

The verification state of the violation (detect alarm).

Type: String

Valid Values: FALSE_POSITIVE | BENIGN_POSITIVE | TRUE_POSITIVE | UNKNOWN

Required: No
verificationStateDescription

The description of the verification state of the violation.

857
 AWS IoT API Reference
ActiveViolation

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [^\p{Cntrl}]*

Required: No
violationEventAdditionalInfo

The details of a violation event.

Type: ViolationEventAdditionalInfo (p. 1123) object

Required: No
violationId

The ID of the active violation.

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

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

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

860
 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

861
 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. 1028) 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

862
 AWS IoT API Reference
AssetPropertyTimestamp

AssetPropertyTimestamp
Service: AWS IoT

An asset property timestamp entry containing the following information.

Contents
timeInSeconds

A string that contains the time in seconds since epoch. Accepts substitution templates.

Type: String

Required: Yes
offsetInNanos

Optional. A string that contains the nanosecond time offset. Accepts substitution templates.

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

863
 AWS IoT API Reference
AssetPropertyValue

AssetPropertyValue
Service: AWS IoT

An asset property value entry containing the following information.

Contents
timestamp

The asset property value timestamp.

Type: AssetPropertyTimestamp (p. 863) object

Required: Yes
value

The value of the asset property.

Type: AssetPropertyVariant (p. 865) object

Required: Yes
quality

Optional. A string that describes the quality of the value. Accepts substitution templates. Must be
GOOD, BAD, or UNCERTAIN.

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

864
 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

865
 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

866
 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

867
 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

868
 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

869
 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. 1014) 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

870
 AWS IoT API Reference
AuditFinding

Required: No
relatedResources

The list of related resources.

Type: Array of RelatedResource (p. 1042) 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

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

872
 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

873
 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

874
 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

875
 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

876
 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
resourceIdentifier

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 1045) object

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

877
 AWS IoT API Reference
AuditSuppression

• AWS SDK for Ruby V3

878
 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

879
 AWS IoT API Reference
AuthInfo

AuthInfo
Service: AWS IoT

A collection of authorization information.

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

Pattern: [\s\S]*

Required: Yes
actionType

The type of action for which the principal is being authorized.

Type: String

Valid Values: PUBLISH | SUBSCRIBE | RECEIVE | CONNECT

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

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

Pattern: [\s\S]*

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
enableCachingForHttp

When true, the result from the authorizer’s Lambda function is cached for the time specified
in refreshAfterInSeconds. The cached result is used while the device reuses the same HTTP
connection.

Type: Boolean

Required: No
lastModifiedDate

The UNIX timestamp of when the authorizer was last updated.

Type: Timestamp

882
 AWS IoT API Reference
AuthorizerDescription

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.

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.

Value Pattern: [\s\S]*

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

884
 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. 862) 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. 880) object

Required: No
denied

The policies and statements that denied the specified action.

Type: Denied (p. 923) 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

885
 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. 887) 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

886
 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

887
AWS IoT API Reference
AwsJobAbortCriteria

888
 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. 890) 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

889
 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. 892) 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

890
 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

891
 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

892
 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

893
 AWS IoT API Reference
Behavior

Behavior
Service: AWS IoT

A Device Defender security profile behavior.

Contents
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
criteria

The criteria that determine if a device is behaving normally in regard to the metric.
Note
In the AWS IoT console, you can choose to be sent an alert through Amazon SNS when AWS
IoT Device Defender detects that a device is behaving anomalously.

Type: BehaviorCriteria (p. 896) object

Required: No
exportMetric

Value indicates exporting metrics related to the behavior when it is true.

Type: Boolean

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. 1002) object

Required: No
suppressAlerts

Suppresses alerts.

Type: Boolean

Required: No

894
 AWS IoT API Reference
Behavior

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

896
 AWS IoT API Reference
BehaviorCriteria

Type: MachineLearningDetectionConfig (p. 997) 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. 1068) object

Required: No
value

The value to be compared with the metric.

Type: MetricValue (p. 1005) 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

897
 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

898
 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

899
 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

900
 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

901
 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

902
 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. 1081) 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

903
 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

904
 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
certificateMode

The mode of the CA.

All the device certificates that are registered using this CA will be registered in the same mode as the
CA. For more information about certificate mode for device certificates, see certificate mode.

Type: String

Valid Values: DEFAULT | SNI_ONLY

Required: No
certificatePem

The CA certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*

Required: No

905
 AWS IoT API Reference
CACertificateDescription

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.

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. 913) object

Required: No

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

906
 AWS IoT API Reference
CACertificateDescription

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

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

DEFAULT: A certificate in DEFAULT mode is either generated by AWS IoT Core or registered with an
issuer certificate authority (CA) in DEFAULT mode. Devices with certificates in DEFAULT mode aren't
required to send the Server Name Indication (SNI) extension when connecting to AWS IoT Core.
However, to use features such as custom domains and VPC endpoints, we recommend that you use
the SNI extension when connecting to AWS IoT Core.

SNI_ONLY: A certificate in SNI_ONLY mode is registered without an issuer CA. Devices with
certificates in SNI_ONLY mode must send the SNI extension when connecting to AWS IoT Core.

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

908
 AWS IoT API Reference
Certificate

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

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

DEFAULT: A certificate in DEFAULT mode is either generated by AWS IoT Core or registered with an
issuer certificate authority (CA) in DEFAULT mode. Devices with certificates in DEFAULT mode aren't
required to send the Server Name Indication (SNI) extension when connecting to AWS IoT Core.
However, to use features such as custom domains and VPC endpoints, we recommend that you use
the SNI extension when connecting to AWS IoT Core.

SNI_ONLY: A certificate in SNI_ONLY mode is registered without an issuer CA. Devices with
certificates in SNI_ONLY mode must send the SNI extension when connecting to AWS IoT Core.

For more information about the value for SNI extension, see Transport security in AWS IoT.

Type: String

Valid Values: DEFAULT | SNI_ONLY

Required: No
certificatePem

The certificate data, in PEM format.

910
 AWS IoT API Reference
CertificateDescription

Type: String

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

Pattern: [\s\S]*

Required: No
creationDate

The date and time the certificate was created.

Type: Timestamp

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

911
 AWS IoT API Reference
CertificateDescription

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.

Type: TransferData (p. 1114) object

Required: No
validity

When the certificate is valid.

Type: CertificateValidity (p. 913) 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

912
 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

913
 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

914
 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
batchMode

Indicates whether batches of log records will be extracted and uploaded into CloudWatch. Values
include true or false (default).

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

915
 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
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
metricTimestamp

An optional Unix timestamp.

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

916
 AWS IoT API Reference
CloudwatchMetricAction

• AWS SDK for Ruby V3

917
 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. 922) object

Required: No
startSigningJobParameter

Describes the code-signing job.

Type: StartSigningJobParameter (p. 1067) 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

918
 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

919
 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

920
 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

921
 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. 919) object

Required: No
hashAlgorithm

The hash algorithm used to code sign the file. You can use a string as the algorithm name if the
target over-the-air (OTA) update devices are able to verify the signature that was generated using
the same signature algorithm. For example, FreeRTOS uses SHA256 or SHA1, so you can pass either
of them based on which was used for generating the signature.

Type: String

Required: No
signature

The signature for the file.

Type: CodeSigningSignature (p. 920) object

Required: No
signatureAlgorithm

The signature algorithm used to code sign the file. You can use a string as the algorithm name if the
target over-the-air (OTA) update devices are able to verify the signature that was generated using
the same signature algorithm. For example, FreeRTOS uses ECDSA or RSA, so you can pass either of
them based on which was used for generating the signature.

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

922
 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. 942) 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. 958) 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

923
 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. 1051) 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

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

925
 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

926
 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

927
 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. 1007) 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. 930) 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

928
 AWS IoT API Reference
DetectMitigationActionsTaskSummary

Required: No
taskStatistics

The statistics of a mitigation action task.

Type: DetectMitigationActionsTaskStatistics (p. 927) 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. 1124) 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

929
 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

930
 AWS IoT API Reference
DocumentParameter

DocumentParameter
Service: AWS IoT

A map of key-value pairs containing the patterns that need to be replaced in a managed template job
document schema. You can use the description of each key as a guidance to specify the inputs during
runtime when creating a job.
Note
documentParameters can only be used when creating jobs from AWS managed templates.
This parameter can't be used with custom job templates or to create jobs from them.

Contents
description

Description of the map field containing the patterns that need to be replaced in a managed
template job document schema.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
example

An example illustrating a pattern that need to be replaced in a managed template job document
schema.

Type: String

Pattern: [^\p{C}]+

Required: No
key

Key of the map field containing the patterns that need to be replaced in a managed template job
document schema.

Type: String

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

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

Required: No
optional

Specifies whether a pattern that needs to be replaced in a managed template job document schema
is optional or required.

Type: Boolean

Required: No
regex

A regular expression of the patterns that need to be replaced in a managed template job document
schema.

931
 AWS IoT API Reference
DocumentParameter

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

932
 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

933
 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
hashKeyValue

The hash key value.

Type: String

Required: Yes
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
hashKeyType

The hash key type. Valid values are "STRING" or "NUMBER"

Type: String

Valid Values: STRING | NUMBER

934
 AWS IoT API Reference
DynamoDBAction

Required: No
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.

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

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

936
 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

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

Pattern: [\s\S]*

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

937
 AWS IoT API Reference
ElasticsearchAction

ElasticsearchAction
Service: AWS IoT

Describes an action that writes data to an Amazon OpenSearch Service domain.

Note
The Elasticsearch action can only be used by existing rule actions. To create a new rule
action or to update an existing rule action, use the OpenSearch rule action instead. For more
information, see OpenSearchAction.

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

938
 AWS IoT API Reference
ElasticsearchAction

• AWS SDK for Ruby V3

939
 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

940
 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

941
 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. 1028) 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

942
 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.1. Maximum value of 5.

Required: Yes
rateIncreaseCriteria

The criteria to initiate the increase in rate of rollout for a job.

Type: RateIncreaseCriteria (p. 1040) 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

943
 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

944
 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. 1052) object

Required: No
stream

The stream that contains the OTA update.

Type: Stream (p. 1072) 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

945
 AWS IoT API Reference
FirehoseAction

FirehoseAction
Service: AWS IoT

Describes an action that writes data to an Amazon Kinesis Firehose stream.

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

946
 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

947
 AWS IoT API Reference
GeoLocationTarget

GeoLocationTarget
Service: AWS IoT

A geolocation target that you select to index. Each geolocation target contains a name and order key-
value pair that specifies the geolocation target fields.

Contents
name

The name of the geolocation target field. If the target field is part of a named shadow, you must
select the named shadow using the namedShadow filter.

Type: String

Required: No
order

The order of the geolocation target field. This field is optional. The default value is LatLon.

Type: String

Valid Values: LatLon | LonLat

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

949
 AWS IoT API Reference
HttpAction

HttpAction
Service: AWS IoT

Send data to an HTTPS endpoint.

Contents
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
auth

The authentication method to use when sending data to an HTTPS endpoint.

Type: HttpAuthorization (p. 953) 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. 952) objects

Array Members: Minimum number of 0 items. Maximum number of 100 items.

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

950
AWS IoT API Reference
HttpAction

951
 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

952
 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. 1064) 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

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

Key Pattern: [\s\S]*

Value Length Constraints: Minimum length of 1. Maximum length of 8192.

Value Pattern: [\s\S]*

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.

Pattern: [\s\S]*

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

955
 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

956
 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

957
 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. 1028) 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

958
 AWS IoT API Reference
IndexingFilter

IndexingFilter
Service: AWS IoT

Provides additional selections for named shadows and geolocation data.

To add named shadows to your fleet indexing configuration, set namedShadowIndexingMode to be ON

and specify your shadow names in namedShadowNames filter.

To add geolocation data to your fleet indexing configuration:

• If you store geolocation data in a class/unnamed shadow, set thingIndexingMode to be

REGISTRY_AND_SHADOW and specify your geolocation data in geoLocations filter.
• If you store geolocation data in a named shadow, set namedShadowIndexingMode to be ON, add
the shadow name in namedShadowNames filter, and specify your geolocation data in geoLocations
filter. For more information, see Managing fleet indexing.

Contents
geoLocations

The list of geolocation targets that you select to index. The default maximum number of geolocation
targets for indexing is 1. To increase the limit, see AWS IoT Device Management Quotas in the AWS
General Reference.

Type: Array of GeoLocationTarget (p. 948) objects

Required: No
namedShadowNames

The shadow names that you select to index. The default maximum number of shadow names for
indexing is 10. To increase the limit, see AWS IoT Device Management Quotas in the AWS General
Reference.

Type: Array of strings

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

959
 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

960
 AWS IoT API Reference
IotEventsAction

IotEventsAction
Service: AWS IoT

Sends an input to an AWS IoT Events detector.

Contents
inputName

The name of the AWS IoT Events input.

Type: String

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

Required: Yes
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
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
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

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

• AWS SDK for C++

961
 AWS IoT API Reference
IotEventsAction

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

962
 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. 1037) 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

963
 AWS IoT API Reference
IssuerCertificateIdentifier

IssuerCertificateIdentifier
Service: AWS IoT

The certificate issuer indentifier.

Contents
issuerCertificateSerialNumber

The issuer certificate serial number.

Type: String

Length Constraints: Maximum length of 20.

Pattern: [a-fA-F0-9:]+

Required: No
issuerCertificateSubject

The subject of the issuer certificate.

Type: String

Length Constraints: Maximum length of 1000.

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

Required: No
issuerId

The issuer ID.

Type: String

Length Constraints: Maximum length of 64.

Pattern: (0x)?[a-fA-F0-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

964
 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. 850) 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
destinationPackageVersions

The package version Amazon Resource Names (ARNs) that are installed on the device when the job
successfully completes.

Note:The following Length Constraints relates to a single ARN. Up to 25 package version ARNs are
allowed.

Type: Array of strings

965
 AWS IoT API Reference
Job

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

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

Required: No
documentParameters

A key-value map that pairs the patterns that need to be replaced in a managed template job
document schema. You can use the description of each key as a guidance to specify the inputs
during runtime when creating a job.
Note
documentParameters can only be used when creating jobs from AWS managed
templates. This parameter can't be used with custom job templates or to create jobs from
them.

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. Maximum length of 512.

Value 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
isConcurrent

Indicates whether a job is concurrent. Will be true when a job is rolling out new job executions or
canceling previously created executions, otherwise false.

Type: Boolean

Required: No
jobArn

An ARN identifying the job with format "arn:aws:iot:region:account:job/jobId".

Type: String

Required: No
jobExecutionsRetryConfig

The configuration for the criteria to retry the job.

Type: JobExecutionsRetryConfig (p. 972) object

Required: No
jobExecutionsRolloutConfig

Allows you to create a staged rollout of a job.

966
 AWS IoT API Reference
Job

Type: JobExecutionsRolloutConfig (p. 973) 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. 979) 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

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

Required: No
presignedUrlConfig

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 1031) object

967
 AWS IoT API Reference
Job

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
scheduledJobRollouts

Displays the next seven maintenance window occurrences and their start times.

Type: Array of ScheduledJobRollout (p. 1056) objects

Required: No
schedulingConfig

The configuration that allows you to schedule a job for a future date and time in addition to
specifying the end behavior for each job execution.

Type: SchedulingConfig (p. 1057) object

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 |

SCHEDULED

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.
Note
We recommend that you use continuous jobs instead of snapshot jobs for dynamic thing
group targets. By using continuous jobs, devices that join the group receive the job
execution even after the job has been created.

968
 AWS IoT API Reference
Job

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.

Type: TimeoutConfig (p. 1097) 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
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

970
 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. 974) 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

971
 AWS IoT API Reference
JobExecutionsRetryConfig

JobExecutionsRetryConfig
Service: AWS IoT

The configuration that determines how many retries are allowed for each failure type for a job.

Contents
criteriaList

The list of criteria that determines how many retries are allowed for each failure type for a job.

Type: Array of RetryCriteria (p. 1047) objects

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

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

972
 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. 943) 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

973
 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

974
 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
retryAttempt

The number that indicates how many retry attempts have been completed for this job on this device.

Type: Integer

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:

975
 AWS IoT API Reference
JobExecutionSummary

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

976
 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. 975) 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

977
 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. 975) 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

978
 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

979
 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

980
 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
isConcurrent

Indicates whether a job is concurrent. Will be true when a job is rolling out new job executions or
canceling previously created executions, otherwise false.

Type: Boolean

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

981
 AWS IoT API Reference
JobSummary

Valid Values: IN_PROGRESS | CANCELED | COMPLETED | DELETION_IN_PROGRESS |

SCHEDULED

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 thing when
the thing is added to a target group, even after the job was completed by all things originally in the
group.
Note
We recommend that you use continuous jobs instead of snapshot jobs for dynamic thing
group targets. By using continuous jobs, devices that join the group receive the job
execution even after the job has been created.

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

982
 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

983
AWS IoT API Reference
JobTemplateSummary

984
 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
topic

The Kafka topic for messages to be sent to the Kafka broker.

Type: String

Required: Yes
headers

The list of Kafka headers that you specify.

Type: Array of KafkaActionHeader (p. 987) objects

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

Required: No
key

The Kafka message key.

Type: String

Required: No
partition

The Kafka message partition.

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

985
 AWS IoT API Reference
KafkaAction

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

986
 AWS IoT API Reference
KafkaActionHeader

KafkaActionHeader
Service: AWS IoT

Specifies a Kafka header using key-value pairs when you create a Rule’s Kafka Action. You can use these
headers to route data from IoT clients to downstream Kafka clusters without modifying your message
payload.

For more information about Rule's Kafka action, see Apache Kafka.

Contents
key

The key of the Kafka header.

Type: String

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

Required: Yes
value

The value of the Kafka header.

Type: String

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

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

987
 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

988
 AWS IoT API Reference
KinesisAction

KinesisAction
Service: AWS IoT

Describes an action to write data to an Amazon Kinesis stream.

Contents
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
partitionKey

The partition key.

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

989
 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

990
 AWS IoT API Reference
LocationAction

LocationAction
Service: AWS IoT

The Amazon Location rule action sends device location updates from an MQTT message to an Amazon
Location tracker resource.

Contents
deviceId

The unique ID of the device providing the location data.

Type: String

Required: Yes
latitude

A string that evaluates to a double value that represents the latitude of the device's location.

Type: String

Required: Yes
longitude

A string that evaluates to a double value that represents the longitude of the device's location.

Type: String

Required: Yes
roleArn

The IAM role that grants permission to write to the Amazon Location resource.

Type: String

Required: Yes
trackerName

The name of the tracker resource in Amazon Location in which the location is updated.

Type: String

Required: Yes
timestamp

The time that the location data was sampled. The default value is the time the MQTT message was
processed.

Type: LocationTimestamp (p. 993) 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++

991
 AWS IoT API Reference
LocationAction

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

992
 AWS IoT API Reference
LocationTimestamp

LocationTimestamp
Service: AWS IoT

Describes how to interpret an application-defined timestamp value from an MQTT message payload and
the precision of that value.

Contents
value

An expression that returns a long epoch time value.

Type: String

Required: Yes
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: 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
LoggingOptionsPayload

LoggingOptionsPayload
Service: AWS IoT

Describes the logging options payload.

Contents
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes
logLevel

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

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

994
 AWS IoT API Reference
LogTarget

LogTarget
Service: AWS IoT

A log target.

Contents
targetType

The target type.

Type: String

Valid Values: DEFAULT | THING_GROUP | CLIENT_ID | SOURCE_IP | PRINCIPAL_ID |

EVENT_TYPE | DEVICE_DEFENDER

Required: Yes
targetName

The target name.

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

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

997
 AWS IoT API Reference
MaintenanceWindow

MaintenanceWindow
Service: AWS IoT

An optional configuration within the SchedulingConfig to setup a recurring maintenance window

with a predetermined start time and duration for the rollout of a job document to all devices in a target
group for a job.

Contents
durationInMinutes

Displays the duration of the next maintenance window.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1430.

Required: Yes
startTime

Displays the start time of the next maintenance window.

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
• AWS SDK for Java V2
• AWS SDK for Ruby V3

998
 AWS IoT API Reference
ManagedJobTemplateSummary

ManagedJobTemplateSummary
Service: AWS IoT

An object that contains information about the managed template.

Contents
description

The description for a managed template.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
environments

A list of environments that are supported with the managed job template.

Type: Array of strings

Pattern: [^\p{C}]+

Required: No
templateArn

The Amazon Resource Name (ARN) for a managed template.

Type: String

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

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

Required: No
templateName

The unique Name for a managed template.

Type: String

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

Required: No
templateVersion

The version for a managed template.

Type: String

Pattern: ^[1-9]+.[0-9]+

Required: No

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

999
 AWS IoT API Reference
ManagedJobTemplateSummary

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1000
 AWS IoT API Reference
MetricDatum

MetricDatum
Service: AWS IoT

A metric.

Contents
timestamp

The time the metric value was reported.

Type: Timestamp

Required: No
value

The value reported for the metric.

Type: MetricValue (p. 1005) 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

1001
 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

1002
 AWS IoT API Reference
MetricsExportConfig

MetricsExportConfig
Service: AWS IoT

Set configurations for metrics export.

Contents
mqttTopic

The MQTT topic that Device Defender Detect should publish messages to for metrics export.

Type: String

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

Required: Yes
roleArn

This role ARN has permission to publish MQTT messages, after which Device Defender Detect can
assume the role and publish messages on your behalf.

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

1003
 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
exportMetric

Value added in both Behavior and AdditionalMetricsToRetainV2 to indicate if Device Defender Detect
should export the corresponding metrics.

Type: Boolean

Required: No
metricDimension

The dimension of a metric. This can't be used with custom metrics.

Type: MetricDimension (p. 1002) 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

1004
 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

1005
 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

1006
 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. 1009) 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

1007
 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

1008
 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. 859) 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. 940) 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. 1036) object

Required: No
replaceDefaultPolicyVersionParams

Parameters to define a mitigation action that adds a blank policy to restrict permissions.

Type: ReplaceDefaultPolicyVersionParams (p. 1043) object

Required: No
updateCACertificateParams

Parameters to define a mitigation action that changes the state of the CA certificate to inactive.

Type: UpdateCACertificateParams (p. 1116) object

Required: No
updateDeviceCertificateParams

Parameters to define a mitigation action that changes the state of the device certificate to inactive.

Type: UpdateDeviceCertificateParams (p. 1117) object

Required: No

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

1009
 AWS IoT API Reference
MitigationActionParams

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

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

Pattern: [\s\S]*

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.

Pattern: [\s\S]*

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
MqttHeaders

MqttHeaders
Service: AWS IoT

Specifies MQTT Version 5.0 headers information. For more information, see MQTT from AWS IoT Core
Developer Guide.

Contents
contentType

A UTF-8 encoded string that describes the content of the publishing message.

For more information, see Content Type from the MQTT Version 5.0 specification.

Supports substitution templates.

Type: String

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

Required: No
correlationData

The base64-encoded binary data used by the sender of the request message to identify which
request the response message is for when it's received.

For more information, see Correlation Data from the MQTT Version 5.0 specification.
Note
This binary data must be based64-encoded.

Supports substitution templates.

Type: String

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

Required: No
messageExpiry

A user-defined integer value that will persist a message at the message broker for a specified
amount of time to ensure that the message will expire if it's no longer relevant to the subscriber. The
value of messageExpiry represents the number of seconds before it expires. For more information
about the limits of messageExpiry, see AWS IoT Core message broker and protocol limits and
quotas from the AWS Reference Guide.

Supports substitution templates.

Type: String

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

Required: No
payloadFormatIndicator

An Enum string value that indicates whether the payload is formatted as UTF-8.

Valid values are UNSPECIFIED_BYTES and UTF8_DATA.

For more information, see Payload Format Indicator from the MQTT Version 5.0 specification.

1012
 AWS IoT API Reference
MqttHeaders

Supports substitution templates.

Type: String

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

Required: No
responseTopic

A UTF-8 encoded string that's used as the topic name for a response message. The response topic is
used to describe the topic which the receiver should publish to as part of the request-response flow.
The topic must not contain wildcard characters.

For more information, see Response Topic from the MQTT Version 5.0 specification.

Supports substitution templates.

Type: String

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

Required: No
userProperties

An array of key-value pairs that you define in the MQTT5 header.

Type: Array of UserProperty (p. 1118) objects

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

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

1013
 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. 1045) 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
| ISSUER_CERTIFICATE

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

1014
 AWS IoT API Reference
OpenSearchAction

OpenSearchAction
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 OpenSearch 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

1015
 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. They won't be sent to devices as a part of the Job document.

Type: String to string map

Value Length Constraints: Minimum length of 0. Maximum length of 4096.

Value Pattern: [\s\S]*

Required: No
codeSigning

The code signing method of the file.

Type: CodeSigning (p. 918) object

Required: No
fileLocation

The location of the updated firmware.

Type: FileLocation (p. 945) 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

1016
 AWS IoT API Reference
OTAUpdateFile

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
OTAUpdateInfo

OTAUpdateInfo
Service: AWS IoT

Information about an OTA update.

Contents
additionalParameters

A collection of name/value pairs

Type: String to string map

Value Length Constraints: Minimum length of 0. Maximum length of 4096.

Value Pattern: [\s\S]*

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. 889) object

Required: No
awsJobPresignedUrlConfig

Configuration information for pre-signed URLs. Valid when protocols contains HTTP.

Type: AwsJobPresignedUrlConfig (p. 891) 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

1018
 AWS IoT API Reference
OTAUpdateInfo

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
errorInfo

Error information associated with the OTA update.

Type: ErrorInfo (p. 941) 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. 1016) objects

Array Members: Minimum number of 1 item.

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

1019
 AWS IoT API Reference
OTAUpdateInfo

Type: Array of strings

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

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

1020
 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

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

Pattern: [\s\S]*

Required: No
transferredTo

The AWS account to which the transfer was made.

Type: String

Length Constraints: Fixed length of 12.

Pattern: [0-9]+

1022
 AWS IoT API Reference
OutgoingCertificate

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

1023
 AWS IoT API Reference
PackageSummary

PackageSummary
Service: AWS IoT

A summary of information about a software package.

Contents
creationDate

The date that the package was created.

Type: Timestamp

Required: No
defaultVersionName

The name of the default package version.

Type: String

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

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

Required: No
lastModifiedDate

The date that the package was last updated.

Type: Timestamp

Required: No
packageName

The name for the target software package.

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

1024
 AWS IoT API Reference
PackageVersionSummary

PackageVersionSummary
Service: AWS IoT

A summary of information about a package version.

Contents
creationDate

The date that the package version was created.

Type: Timestamp

Required: No
lastModifiedDate

The date that the package version was last updated.

Type: Timestamp

Required: No
packageName

The name of the associated software package.

Type: String

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

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

Required: No
status

The status of the package version. For more information, see Package version lifecycle.

Type: String

Valid Values: DRAFT | PUBLISHED | DEPRECATED

Required: No
versionName

The name of the target package version.

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

1025
 AWS IoT API Reference
PackageVersionSummary

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1026
 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

1027
 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

1028
 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

1029
 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

1030
 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 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.
Important
For information about addressing the confused deputy problem, see cross-service confused
deputy prevention in the AWS IoT Core developer guide.

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

1031
 AWS IoT API Reference
ProvisioningHook

ProvisioningHook
Service: AWS IoT

Structure that contains payloadVersion and targetArn.

Contents
targetArn

The ARN of the target function.

Note: Only Lambda functions are currently supported.

Type: String

Length Constraints: Maximum length of 2048.

Required: Yes
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

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

1032
 AWS IoT API Reference
ProvisioningTemplateSummary

ProvisioningTemplateSummary
Service: AWS IoT

A summary of information about a provisioning template.

Contents
creationDate

The date when the provisioning template summary was created.

Type: Timestamp

Required: No
description

The description of the 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 provisioning template summary was last modified.

Type: Timestamp

Required: No
templateArn

The ARN of the provisioning template.

Type: String

Required: No
templateName

The name of the provisioning template.

Type: String

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

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

Required: No

1033
 AWS IoT API Reference
ProvisioningTemplateSummary

type

The type you define in a provisioning template. You can create a template with only one type. You
can't change the template type after its creation. The default value is FLEET_PROVISIONING. For
more information about provisioning template, see: Provisioning template.

Type: String

Valid Values: FLEET_PROVISIONING | JITP

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
ProvisioningTemplateVersionSummary

ProvisioningTemplateVersionSummary
Service: AWS IoT

A summary of information about a fleet provision template version.

Contents
creationDate

The date when the provisioning template version was created

Type: Timestamp

Required: No
isDefaultVersion

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

Type: Boolean

Required: No
versionId

The ID of the fleet provisioning 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

1035
 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

1036
 AWS IoT API Reference
PutAssetPropertyValueEntry

PutAssetPropertyValueEntry
Service: AWS IoT

An asset property value entry containing the following information.

Contents
propertyValues

A list of property values to insert that each contain timestamp, quality, and value (TQV) information.

Type: Array of AssetPropertyValue (p. 864) objects

Array Members: Minimum number of 1 item.

Required: Yes
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

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

1037
 AWS IoT API Reference
PutAssetPropertyValueEntry

• AWS SDK for Java V2

• AWS SDK for Ruby V3

1038
 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

1039
 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

1040
 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

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

Pattern: [\s\S]*

Required: No
templateName

The name of the provisioning template.

Type: String

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

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

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

1041
 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. 1045) 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
| ISSUER_CERTIFICATE

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

1043
 AWS IoT API Reference
RepublishAction

RepublishAction
Service: AWS IoT

Describes an action to republish to another topic.

Contents
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
headers

MQTT Version 5.0 headers information. For more information, see MQTT from the AWS IoT Core
Developer Guide.

Type: MqttHeaders (p. 1012) object

Required: No
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

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

The ARN of the identified device certificate.

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]+

1045
 AWS IoT API Reference
ResourceIdentifier

Required: No
iamRoleArn

The ARN of the IAM role that has overly permissive actions.

Type: String

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

Required: No
issuerCertificateIdentifier

The issuer certificate identifier.

Type: IssuerCertificateIdentifier (p. 964) object

Required: No
policyVersionIdentifier

The version of the policy associated with the resource.

Type: PolicyVersionIdentifier (p. 1030) 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

1046
 AWS IoT API Reference
RetryCriteria

RetryCriteria
Service: AWS IoT

The criteria that determines how many retries are allowed for each failure type for a job.

Contents
failureType

The type of job execution failures that can initiate a job retry.

Type: String

Valid Values: FAILED | TIMED_OUT | ALL

Required: Yes
numberOfRetries

The number of retries allowed for a failure type for the job.

Type: Integer

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

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

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

1048
 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

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

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

1051
 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

1052
 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

1053
 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:

1054
 AWS IoT API Reference
ScheduledAuditMetadata

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1055
 AWS IoT API Reference
ScheduledJobRollout

ScheduledJobRollout
Service: AWS IoT

Displays the next seven maintenance window occurrences and their start times.

Contents
startTime

Displays the start times of the next seven maintenance window occurrences.

Type: String

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

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

1056
 AWS IoT API Reference
SchedulingConfig

SchedulingConfig
Service: AWS IoT

Specifies the date and time that a job will begin the rollout of the job document to all devices in the
target group. Additionally, you can specify the end behavior for each job execution when it reaches the
scheduled end time.

Contents
endBehavior

Specifies the end behavior for all job executions after a job reaches the selected endTime. If
endTime is not selected when creating the job, then endBehavior does not apply.

Type: String

Valid Values: STOP_ROLLOUT | CANCEL | FORCE_CANCEL

Required: No
endTime

The time a job will stop rollout of the job document to all devices in the target group for a job.
The endTime must take place no later than two years from the current time and be scheduled a
minimum of thirty minutes from the current time. The minimum duration between startTime and
endTime is thirty minutes. The maximum duration between startTime and endTime is two years.
The date and time format for the endTime is YYYY-MM-DD for the date and HH:MM for the time.

For more information on the syntax for endTime when using an API command or the AWS
Command Line Interface, see Timestamp.

Type: String

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

Required: No
maintenanceWindows

An optional configuration within the SchedulingConfig to setup a recurring maintenance window

with a predetermined start time and duration for the rollout of a job document to all devices in a
target group for a job.

Type: Array of MaintenanceWindow (p. 998) objects

Required: No
startTime

The time a job will begin rollout of the job document to all devices in the target group for a job. The
startTime can be scheduled up to a year in advance and must be scheduled a minimum of thirty
minutes from the current time. The date and time format for the startTime is YYYY-MM-DD for
the date and HH:MM for the time.

For more information on the syntax for startTime when using an API command or the AWS
Command Line Interface, see Timestamp.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: No

1057
 AWS IoT API Reference
SchedulingConfig

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

1058
 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

1059
 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

1060
 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. 1059) object

Required: No
target

Information about the target (thing group) associated with the security profile.

Type: SecurityProfileTarget (p. 1060) 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

1061
 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

1062
 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

1063
 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

1064
 AWS IoT API Reference
SnsAction

SnsAction
Service: AWS IoT

Describes an action to publish to an Amazon SNS topic.

Contents
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
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

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

1065
 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

1066
 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. 924) object

Required: No
signingProfileName

The code-signing profile name.

Type: String

Required: No
signingProfileParameter

Describes the code-signing profile.

Type: SigningProfileParameter (p. 1063) 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

1067
 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

1068
 AWS IoT API Reference
Statistics

Statistics
Service: AWS IoT

A map of key-value pairs for all supported statistics. For issues with missing or unexpected values for this
API, consult Fleet indexing troubleshooting guide.

Contents
average

The average of the aggregated field values.

Type: Double

Required: No
count

The count of things that match the query string criteria and contain a valid aggregation field value.

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

1069
 AWS IoT API Reference
Statistics

variance

The variance of the aggregated field values.

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

1070
 AWS IoT API Reference
StepFunctionsAction

StepFunctionsAction
Service: AWS IoT

Starts execution of a Step Functions state machine.

Contents
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
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

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

1071
 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

1072
 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. 1052) 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

1073
 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. 1073) 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.

1074
 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

1075
 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

1076
 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 0. 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

1077
 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

1078
 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

1079
 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

1080
 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

1081
 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

1082
 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

1083
 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

1084
 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. 1084) object

Required: No
deviceDefender

Contains Device Defender data.

For more information about Device Defender, see Device Defender.

Type: String

Required: No
shadow

The unnamed shadow and named shadow.

For more information about shadows, see AWS IoT Device Shadow service.

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

1085
 AWS IoT API Reference
ThingDocument

thingId

The thing ID.

Type: String

Required: No
thingName

The thing name.

Type: String

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

1086
 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

1087
 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

1088
 AWS IoT API Reference
ThingGroupIndexingConfiguration

ThingGroupIndexingConfiguration
Service: AWS IoT

Thing group indexing configuration.

Contents
thingGroupIndexingMode

Thing group indexing mode.

Type: String

Valid Values: OFF | ON

Required: Yes
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. 944) objects

Required: No
managedFields

Contains fields that are indexed and whose types are already known by the Fleet Indexing service.
This is an optional field. For more information, see Managed fields in the AWS IoT Core Developer
Guide.
Note
You can't modify managed fields by updating fleet indexing configuration.

Type: Array of Field (p. 944) 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

1089
 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. 949) 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

1090
 AWS IoT API Reference
ThingGroupProperties

ThingGroupProperties
Service: AWS IoT

Thing group properties.

Contents
attributePayload

The thing group attributes in JSON format.

Type: AttributePayload (p. 866) 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

1091
 AWS IoT API Reference
ThingIndexingConfiguration

ThingIndexingConfiguration
Service: AWS IoT

The thing indexing configuration. For more information, see Managing Thing Indexing.

Contents
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
customFields

Contains custom field names and their data type.

Type: Array of Field (p. 944) objects

Required: No
deviceDefenderIndexingMode

Device Defender indexing mode. Valid values are:

• VIOLATIONS – Your thing index contains Device Defender violations. To enable Device Defender
indexing, deviceDefenderIndexingMode must not be set to OFF.
• OFF - Device Defender indexing is disabled.

For more information about Device Defender violations, see Device Defender Detect.

Type: String

Valid Values: OFF | VIOLATIONS

Required: No
filter

Provides additional selections for named shadows and geolocation data.

To add named shadows to your fleet indexing configuration, set namedShadowIndexingMode to be

ON and specify your shadow names in namedShadowNames filter.

To add geolocation data to your fleet indexing configuration:

• If you store geolocation data in a class/unnamed shadow, set thingIndexingMode to be
REGISTRY_AND_SHADOW and specify your geolocation data in geoLocations filter.
• If you store geolocation data in a named shadow, set namedShadowIndexingMode to be
ON, add the shadow name in namedShadowNames filter, and specify your geolocation data in
geoLocations filter. For more information, see Managing fleet indexing.

Type: IndexingFilter (p. 959) object

Required: No

1092
 AWS IoT API Reference
ThingIndexingConfiguration

managedFields

Contains fields that are indexed and whose types are already known by the Fleet Indexing service.
This is an optional field. For more information, see Managed fields in the AWS IoT Core Developer
Guide.
Note
You can't modify managed fields by updating fleet indexing configuration.

Type: Array of Field (p. 944) objects

Required: No
namedShadowIndexingMode

Named shadow indexing mode. Valid values are:

• ON – Your thing index contains named shadow. To enable thing named shadow indexing,
namedShadowIndexingMode must not be set to OFF.
• OFF - Named shadow indexing is disabled.

For more information about Shadows, see AWS IoT Device Shadow service.

Type: String

Valid Values: OFF | ON

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

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

1093
 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. 1095) 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. 1096) 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

1094
 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

1095
 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

1096
 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

1097
 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. 1100) 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. 1101) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

1098
 AWS IoT API Reference
TimestreamAction

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1099
 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

1100
 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

1101
 AWS IoT API Reference
TlsConfig

TlsConfig
Service: AWS IoT

An object that specifies the TLS configuration for a domain.

Contents
securityPolicy

The security policy for a domain configuration. For more information, see Security policies in the
AWS IoT Core developer guide.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\s\S]*

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

1102
 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.

Pattern: [\s\S]*

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

1103
 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. 853) 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. 853) 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.

1104
 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

1105
 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. 956) 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

1106
 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. 1126) 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

1107
 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. 955) object

Required: No
vpcConfiguration

Configuration of the virtual private cloud (VPC) connection.

Type: VpcDestinationConfiguration (p. 1125) 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

1108
 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. 957) 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

1109
 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. 1127) 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

1110
 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

1111
 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. 853) objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: Yes
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
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. 853) object

Required: No
ruleDisabled

Specifies whether the rule is disabled.

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++

1112
 AWS IoT API Reference
TopicRulePayload

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1113
 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.

Pattern: [\s\S]*

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.

Pattern: [\s\S]*

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

1114
 AWS IoT API Reference
TransferData

• AWS SDK for Java V2

• AWS SDK for Ruby V3

1115
 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

1116
 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

1117
 AWS IoT API Reference
UserProperty

UserProperty
Service: AWS IoT

A key-value pair that you define in the header. Both the key and the value are either literal strings or
valid substitution templates.

Contents
key

A key to be specified in UserProperty.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: Yes
value

A value to be specified in UserProperty.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

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

1118
 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

1119
 AWS IoT API Reference
VersionUpdateByJobsConfig

VersionUpdateByJobsConfig
Service: AWS IoT

Configuration to manage IoT Job's package version reporting. If configured, Jobs updates the thing's
reserved named shadow with the package version information up on successful job completion.

Note: For each job, the destinationPackageVersions attribute has to be set with the correct data for Jobs
to report to the thing shadow.

Contents
enabled

Indicates whether the Job is enabled or not.

Type: Boolean

Required: No
roleArn

The Amazon Resource Name (ARN) of the role that grants permission to the AWS IoT jobs service to
update the reserved named shadow when the job successfully completes.

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

1120
 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. 894) object

Required: No
metricValue

The value of the metric (the measurement).

Type: MetricValue (p. 1005) 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
verificationState

The verification state of the violation (detect alarm).

Type: String

Valid Values: FALSE_POSITIVE | BENIGN_POSITIVE | TRUE_POSITIVE | UNKNOWN

Required: No
verificationStateDescription

The description of the verification state of the violation.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [^\p{Cntrl}]*

1121
 AWS IoT API Reference
ViolationEvent

Required: No
violationEventAdditionalInfo

The details of a violation event.

Type: ViolationEventAdditionalInfo (p. 1123) object

Required: No
violationEventTime

The time the violation event occurred.

Type: Timestamp

Required: No
violationEventType

The type of violation event.

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

1122
 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

1123
 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

1124
 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
subnetIds

The subnet IDs of the VPC destination.

Type: Array of strings

Required: Yes
vpcId

The ID of the VPC.

Type: String

Required: Yes
securityGroups

The security groups of the VPC destination.

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

1125
 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

1126
 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. 1128)

1127
 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. 1130)

• JobExecutionState (p. 1133)
• JobExecutionSummary (p. 1134)

1128
AWS IoT API Reference
AWS IoT jobs data

1129
 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

1130
 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++

1131
 AWS IoT API Reference
JobExecution

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1132
 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

1133
 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:

1134
 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. 1136)

• GroupResult (p. 1137)
• SuiteDefinitionConfiguration (p. 1138)
• SuiteDefinitionInformation (p. 1140)
• SuiteRunConfiguration (p. 1142)
• SuiteRunInformation (p. 1143)
• TestCaseRun (p. 1145)
• TestCaseScenario (p. 1147)
• TestResult (p. 1149)

1135
 AWS IoT API Reference
DeviceUnderTest

DeviceUnderTest
Service: AWS IoT Core Device Advisor

Information of a test device. A thing ARN, certificate ARN or device role ARN is required.

Contents
certificateArn

Lists device's certificate ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
deviceRoleArn

Lists device's role ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
thingArn

Lists device's 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

1136
 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. 1145) 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

1137
 AWS IoT API Reference
SuiteDefinitionConfiguration

SuiteDefinitionConfiguration
Service: AWS IoT Core Device Advisor

Gets the suite definition configuration.

Contents
devicePermissionRoleArn

Gets the device permission ARN. This is a required parameter.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
rootGroup

Gets the test suite root group. This is a required parameter. For updating or creating the latest
qualification suite, if intendedForQualification is set to true, rootGroup can be an empty
string. If intendedForQualification is false, rootGroup cannot be an empty string. If
rootGroup is empty, and intendedForQualification is set to true, all the qualification tests are
included, and the configuration is default.

For a qualification suite, the minimum length is 0, and the maximum is 2048. For a non-qualification
suite, the minimum length is 1, and the maximum is 2048.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Required: Yes
suiteDefinitionName

Gets the suite definition name. This is a required parameter.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: Yes
devices

Gets the devices configured.

Type: Array of DeviceUnderTest (p. 1136) 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

1138
 AWS IoT API Reference
SuiteDefinitionConfiguration

isLongDurationTest

Verifies if the test suite is a long duration test.

Type: Boolean

Required: No
protocol

Sets the MQTT protocol that is configured in the suite definition.

Type: String

Valid Values: MqttV3_1_1 | MqttV5 | MqttV3_1_1_OverWebSocket |

MqttV5_OverWebSocket

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

1139
 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 that are under test for the test suite.

Type: Array of DeviceUnderTest (p. 1136) 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
isLongDurationTest

Verifies if the test suite is a long duration test.

Type: Boolean

Required: No
protocol

Gets the MQTT protocol that is configured in the suite definition.

Type: String

Valid Values: MqttV3_1_1 | MqttV5 | MqttV3_1_1_OverWebSocket |

MqttV5_OverWebSocket

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.

1140
 AWS IoT API Reference
SuiteDefinitionInformation

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

1141
 AWS IoT API Reference
SuiteRunConfiguration

SuiteRunConfiguration
Service: AWS IoT Core Device Advisor

Gets suite run configuration.

Contents
primaryDevice

Sets the primary device for the test suite run. This requires a thing ARN or a certificate ARN.

Type: DeviceUnderTest (p. 1136) object

Required: Yes
parallelRun

TRUE if multiple test suites run in parallel.

Type: Boolean

Required: No
selectedTestList

Sets 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

1142
 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 | CANCELED | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR

Required: No

1143
 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

1144
 AWS IoT API Reference
TestCaseRun

TestCaseRun
Service: AWS IoT Core Device Advisor

Provides the 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 the test case run status. Status is one of the following:
• 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 | CANCELED | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR

Required: No
testCaseDefinitionId

Provides the test case run definition ID.

1145
 AWS IoT API Reference
TestCaseRun

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
testCaseDefinitionName

Provides the test case run definition name.

Type: String

Required: No
testCaseRunId

Provides the test case run ID.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
testScenarios

Provides the test scenarios for the test case run.

Type: Array of TestCaseScenario (p. 1147) objects

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

1146
 AWS IoT API Reference
TestCaseScenario

TestCaseScenario
Service: AWS IoT Core Device Advisor

Provides test case scenario.

Contents
failure

Provides test case scenario failure result.

Type: String

Required: No
status

Provides the test case scenario status. Status is one of the following:
• 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 | CANCELED | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR

Required: No
systemMessage

Provides test case scenario system messages if any.

Type: String

Required: No
testCaseScenarioId

Provides test case scenario ID.

Type: String

Required: No
testCaseScenarioType

Provides test case scenario type. Type is one of the following:

• Advanced
• Basic

Type: String

Valid Values: Advanced | Basic

1147
 AWS IoT API Reference
TestCaseScenario

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

1148
 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. 1137) 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. 1150)

1149
 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
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
applicationName

The name of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[ -~]*$

Required: Yes
applicationUrl

The URL of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: ^https\://\S+$

Required: Yes
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

1150
 AWS IoT API Reference
AWS IoT Secure Tunneling

applicationLastUpdateDate

The date (in Unix epoch time) when the web application was last updated.

Type: Long

Required: No
applicationState

The current state of the web application.

Type: String

Valid Values: CREATING | DELETING | ACTIVE | CREATE_FAILED | DELETE_FAILED

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 Secure Tunneling

The following data types are supported by AWS IoT Secure Tunneling:

• ConnectionState (p. 1152)

• DestinationConfig (p. 1153)
• Tag (p. 1154)
• TimeoutConfig (p. 1155)
• Tunnel (p. 1156)
• TunnelSummary (p. 1158)

1151
 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

1152
 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

1153
 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

1154
 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

1155
 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. 1153) object

Required: No
destinationConnectionState

The connection state of the destination application.

Type: ConnectionState (p. 1152) 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. 1152) object

Required: No
status

The status of a tunnel. Valid values are: Open and Closed.

Type: String

Valid Values: OPEN | CLOSED

1156
 AWS IoT API Reference
Tunnel

Required: No
tags

A list of tag metadata associated with the secure tunnel.

Type: Array of Tag (p. 1154) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

Required: No
timeoutConfig

Timeout configuration for the tunnel.

Type: TimeoutConfig (p. 1155) object

Required: No
tunnelArn

The Amazon Resource Name (ARN) of a tunnel.

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

1157
 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.

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

1158
 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

1159
 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 Signing AWS API requests in the IAM User Guide.

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 Create a signed AWS API request in the IAM User Guide.

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 not
required. When X-Amz-Date is used, it always overrides the value of the Date header. For more
information, see Elements of an AWS API request signature in the IAM User Guide.

1160
 AWS IoT API 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 STS, see AWS
services that work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from AWS STS, 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 Create a signed AWS API request in the IAM User
Guide.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional

1161