AWS IoT

API Reference
 AWS IoT API Reference

AWS IoT: API Reference

Copyright © 2022 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 ................................................................................................... 15
AddThingToBillingGroup .................................................................................................... 17
AddThingToThingGroup ..................................................................................................... 20
AssociateTargetsWithJob ................................................................................................... 23
AttachPolicy .................................................................................................................... 26
AttachPrincipalPolicy ........................................................................................................ 28
AttachSecurityProfile ........................................................................................................ 30
AttachThingPrincipal ......................................................................................................... 32
CancelAuditMitigationActionsTask ....................................................................................... 34
CancelAuditTask ............................................................................................................... 36
CancelCertificateTransfer ................................................................................................... 38
CancelDetectMitigationActionsTask ..................................................................................... 40
CancelJob ........................................................................................................................ 42
CancelJobExecution .......................................................................................................... 45
ClearDefaultAuthorizer ...................................................................................................... 48
ConfirmTopicRuleDestination ............................................................................................. 50
CreateAuditSuppression ..................................................................................................... 52
CreateAuthorizer .............................................................................................................. 55
CreateBillingGroup ............................................................................................................ 59
CreateCertificateFromCsr ................................................................................................... 62
CreateCustomMetric .......................................................................................................... 65
CreateDimension .............................................................................................................. 68
CreateDomainConfiguration ............................................................................................... 71
CreateDynamicThingGroup ................................................................................................ 75
CreateFleetMetric ............................................................................................................. 79
CreateJob ........................................................................................................................ 84
CreateJobTemplate ........................................................................................................... 90
CreateKeysAndCertificate ................................................................................................... 95
CreateMitigationAction ...................................................................................................... 98
CreateOTAUpdate ........................................................................................................... 101
CreatePolicy ................................................................................................................... 107
CreatePolicyVersion ......................................................................................................... 110
CreateProvisioningClaim .................................................................................................. 113
CreateProvisioningTemplate ............................................................................................. 116
CreateProvisioningTemplateVersion ................................................................................... 120
CreateRoleAlias .............................................................................................................. 123
CreateScheduledAudit ..................................................................................................... 126
CreateSecurityProfile ....................................................................................................... 129
CreateStream ................................................................................................................. 133
CreateThing ................................................................................................................... 137
CreateThingGroup ........................................................................................................... 140
CreateThingType ............................................................................................................. 143
CreateTopicRule .............................................................................................................. 146
CreateTopicRuleDestination .............................................................................................. 155
DeleteAccountAuditConfiguration ..................................................................................... 158

iii
 AWS IoT API Reference

DeleteAuditSuppression ................................................................................................... 160

DeleteAuthorizer ............................................................................................................ 162
DeleteBillingGroup .......................................................................................................... 164
DeleteCACertificate ......................................................................................................... 166
DeleteCertificate ............................................................................................................. 168
DeleteCustomMetric ........................................................................................................ 170
DeleteDimension ............................................................................................................ 172
DeleteDomainConfiguration ............................................................................................. 174
DeleteDynamicThingGroup ............................................................................................... 176
DeleteFleetMetric ........................................................................................................... 178
DeleteJob ...................................................................................................................... 180
DeleteJobExecution ......................................................................................................... 183
DeleteJobTemplate ......................................................................................................... 186
DeleteMitigationAction .................................................................................................... 188
DeleteOTAUpdate ........................................................................................................... 190
DeletePolicy ................................................................................................................... 192
DeletePolicyVersion ......................................................................................................... 194
DeleteProvisioningTemplate ............................................................................................. 196
DeleteProvisioningTemplateVersion ................................................................................... 198
DeleteRegistrationCode ................................................................................................... 200
DeleteRoleAlias .............................................................................................................. 202
DeleteScheduledAudit ..................................................................................................... 204
DeleteSecurityProfile ....................................................................................................... 206
DeleteStream ................................................................................................................. 208
DeleteThing ................................................................................................................... 210
DeleteThingGroup ........................................................................................................... 212
DeleteThingType ............................................................................................................. 214
DeleteTopicRule .............................................................................................................. 216
DeleteTopicRuleDestination .............................................................................................. 218
DeleteV2LoggingLevel ..................................................................................................... 220
DeprecateThingType ....................................................................................................... 222
DescribeAccountAuditConfiguration .................................................................................. 224
DescribeAuditFinding ...................................................................................................... 226
DescribeAuditMitigationActionsTask .................................................................................. 229
DescribeAuditSuppression ................................................................................................ 233
DescribeAuditTask ........................................................................................................... 236
DescribeAuthorizer .......................................................................................................... 239
DescribeBillingGroup ....................................................................................................... 241
DescribeCACertificate ...................................................................................................... 244
DescribeCertificate .......................................................................................................... 247
DescribeCustomMetric ..................................................................................................... 250
DescribeDefaultAuthorizer ............................................................................................... 253
DescribeDetectMitigationActionsTask ................................................................................ 255
DescribeDimension .......................................................................................................... 258
DescribeDomainConfiguration .......................................................................................... 261
DescribeEndpoint ............................................................................................................ 264
DescribeEventConfigurations ............................................................................................ 266
DescribeFleetMetric ......................................................................................................... 268
DescribeIndex ................................................................................................................. 272
DescribeJob ................................................................................................................... 275
DescribeJobExecution ...................................................................................................... 278
DescribeJobTemplate ...................................................................................................... 281
DescribeManagedJobTemplate ......................................................................................... 285
DescribeMitigationAction ................................................................................................. 288
DescribeProvisioningTemplate .......................................................................................... 291
DescribeProvisioningTemplateVersion ................................................................................ 295
DescribeRoleAlias ............................................................................................................ 298

iv
 AWS IoT API Reference

DescribeScheduledAudit .................................................................................................. 300

DescribeSecurityProfile .................................................................................................... 303
DescribeStream .............................................................................................................. 307
DescribeThing ................................................................................................................ 310
DescribeThingGroup ........................................................................................................ 313
DescribeThingRegistrationTask ......................................................................................... 317
DescribeThingType .......................................................................................................... 321
DetachPolicy .................................................................................................................. 324
DetachPrincipalPolicy ...................................................................................................... 326
DetachSecurityProfile ...................................................................................................... 328
DetachThingPrincipal ...................................................................................................... 330
DisableTopicRule ............................................................................................................ 332
EnableTopicRule ............................................................................................................. 334
GetBehaviorModelTrainingSummaries ................................................................................ 336
GetBucketsAggregation ................................................................................................... 338
GetCardinality ................................................................................................................ 342
GetEffectivePolicies ......................................................................................................... 345
GetIndexingConfiguration ................................................................................................ 348
GetJobDocument ............................................................................................................ 351
GetLoggingOptions ......................................................................................................... 353
GetOTAUpdate ............................................................................................................... 355
GetPercentiles ................................................................................................................ 359
GetPolicy ....................................................................................................................... 362
GetPolicyVersion ............................................................................................................. 365
GetRegistrationCode ....................................................................................................... 368
GetStatistics ................................................................................................................... 370
GetTopicRule .................................................................................................................. 373
GetTopicRuleDestination .................................................................................................. 381
GetV2LoggingOptions ..................................................................................................... 383
ListActiveViolations ......................................................................................................... 385
ListAttachedPolicies ........................................................................................................ 388
ListAuditFindings ............................................................................................................ 391
ListAuditMitigationActionsExecutions ................................................................................ 395
ListAuditMitigationActionsTasks ........................................................................................ 398
ListAuditSuppressions ...................................................................................................... 401
ListAuditTasks ................................................................................................................ 404
ListAuthorizers ............................................................................................................... 407
ListBillingGroups ............................................................................................................. 410
ListCACertificates ............................................................................................................ 412
ListCertificates ............................................................................................................... 415
ListCertificatesByCA ........................................................................................................ 418
ListCustomMetrics ........................................................................................................... 421
ListDetectMitigationActionsExecutions ............................................................................... 423
ListDetectMitigationActionsTasks ...................................................................................... 426
ListDimensions ............................................................................................................... 429
ListDomainConfigurations ................................................................................................ 431
ListFleetMetrics .............................................................................................................. 434
ListIndices ...................................................................................................................... 436
ListJobExecutionsForJob .................................................................................................. 438
ListJobExecutionsForThing ............................................................................................... 441
ListJobs ......................................................................................................................... 444
ListJobTemplates ............................................................................................................ 447
ListManagedJobTemplates ............................................................................................... 449
ListMetricValues ............................................................................................................. 451
ListMitigationActions ....................................................................................................... 454
ListOTAUpdates .............................................................................................................. 456
ListOutgoingCertificates .................................................................................................. 459

v
 AWS IoT API Reference

ListPolicies ..................................................................................................................... 462

ListPolicyPrincipals .......................................................................................................... 465
ListPolicyVersions ........................................................................................................... 468
ListPrincipalPolicies ......................................................................................................... 470
ListPrincipalThings .......................................................................................................... 473
ListProvisioningTemplates ................................................................................................ 476
ListProvisioningTemplateVersions ..................................................................................... 478
ListRelatedResourcesForAuditFinding ................................................................................. 481
ListRoleAliases ................................................................................................................ 484
ListScheduledAudits ........................................................................................................ 487
ListSecurityProfiles .......................................................................................................... 489
ListSecurityProfilesForTarget ............................................................................................ 492
ListStreams .................................................................................................................... 495
ListTagsForResource ........................................................................................................ 497
ListTargetsForPolicy ........................................................................................................ 499
ListTargetsForSecurityProfile ............................................................................................ 502
ListThingGroups ............................................................................................................. 504
ListThingGroupsForThing ................................................................................................. 507
ListThingPrincipals .......................................................................................................... 509
ListThingRegistrationTaskReports ...................................................................................... 512
ListThingRegistrationTasks ............................................................................................... 515
ListThings ...................................................................................................................... 517
ListThingsInBillingGroup .................................................................................................. 520
ListThingsInThingGroup ................................................................................................... 522
ListThingTypes ............................................................................................................... 524
ListTopicRuleDestinations ................................................................................................ 527
ListTopicRules ................................................................................................................ 529
ListV2LoggingLevels ........................................................................................................ 531
ListViolationEvents ......................................................................................................... 533
PutVerificationStateOnViolation ....................................................................................... 537
RegisterCACertificate ....................................................................................................... 539
RegisterCertificate .......................................................................................................... 543
RegisterCertificateWithoutCA ........................................................................................... 546
RegisterThing ................................................................................................................. 549
RejectCertificateTransfer .................................................................................................. 552
RemoveThingFromBillingGroup ......................................................................................... 555
RemoveThingFromThingGroup ......................................................................................... 558
ReplaceTopicRule ............................................................................................................ 561
SearchIndex ................................................................................................................... 569
SetDefaultAuthorizer ....................................................................................................... 573
SetDefaultPolicyVersion ................................................................................................... 576
SetLoggingOptions ......................................................................................................... 578
SetV2LoggingLevel ......................................................................................................... 580
SetV2LoggingOptions ..................................................................................................... 582
StartAuditMitigationActionsTask ....................................................................................... 584
StartDetectMitigationActionsTask ..................................................................................... 587
StartOnDemandAuditTask ................................................................................................ 590
StartThingRegistrationTask .............................................................................................. 592
StopThingRegistrationTask ............................................................................................... 595
TagResource ................................................................................................................... 597
TestAuthorization ........................................................................................................... 599
TestInvokeAuthorizer ....................................................................................................... 603
TransferCertificate .......................................................................................................... 607
UntagResource ............................................................................................................... 610
UpdateAccountAuditConfiguration .................................................................................... 612
UpdateAuditSuppression .................................................................................................. 615
UpdateAuthorizer ........................................................................................................... 618

vi
 AWS IoT API Reference

UpdateBillingGroup ......................................................................................................... 622

UpdateCACertificate ........................................................................................................ 625
UpdateCertificate ............................................................................................................ 628
UpdateCustomMetric ....................................................................................................... 631
UpdateDimension ........................................................................................................... 634
UpdateDomainConfiguration ............................................................................................ 637
UpdateDynamicThingGroup ............................................................................................. 640
UpdateEventConfigurations .............................................................................................. 643
UpdateFleetMetric .......................................................................................................... 645
UpdateIndexingConfiguration ........................................................................................... 649
UpdateJob ..................................................................................................................... 652
UpdateMitigationAction ................................................................................................... 656
UpdateProvisioningTemplate ............................................................................................ 659
UpdateRoleAlias ............................................................................................................. 662
UpdateScheduledAudit .................................................................................................... 665
UpdateSecurityProfile ...................................................................................................... 668
UpdateStream ................................................................................................................ 674
UpdateThing .................................................................................................................. 677
UpdateThingGroup ......................................................................................................... 680
UpdateThingGroupsForThing ............................................................................................ 683
UpdateTopicRuleDestination ............................................................................................ 686
ValidateSecurityProfileBehaviors ....................................................................................... 689
AWS IoT data ......................................................................................................................... 691
DeleteThingShadow ........................................................................................................ 692
GetRetainedMessage ....................................................................................................... 695
GetThingShadow ............................................................................................................ 698
ListNamedShadowsForThing ............................................................................................ 701
ListRetainedMessages ...................................................................................................... 704
Publish .......................................................................................................................... 707
UpdateThingShadow ....................................................................................................... 710
AWS IoT jobs data .................................................................................................................. 712
DescribeJobExecution ...................................................................................................... 713
GetPendingJobExecutions ................................................................................................ 716
StartNextPendingJobExecution ......................................................................................... 719
UpdateJobExecution ....................................................................................................... 722
AWS IoT Core Device Advisor ................................................................................................... 725
CreateSuiteDefinition ...................................................................................................... 727
DeleteSuiteDefinition ...................................................................................................... 730
GetEndpoint ................................................................................................................... 732
GetSuiteDefinition .......................................................................................................... 734
GetSuiteRun ................................................................................................................... 737
GetSuiteRunReport ......................................................................................................... 741
ListSuiteDefinitions ......................................................................................................... 743
ListSuiteRuns ................................................................................................................. 745
ListTagsForResource ........................................................................................................ 748
StartSuiteRun ................................................................................................................. 750
StopSuiteRun ................................................................................................................. 753
TagResource ................................................................................................................... 755
UntagResource ............................................................................................................... 757
UpdateSuiteDefinition ..................................................................................................... 759
AWS IoT Fleet Hub ................................................................................................................. 761
CreateApplication ........................................................................................................... 762
DeleteApplication ........................................................................................................... 765
DescribeApplication ........................................................................................................ 767
ListApplications .............................................................................................................. 771
ListTagsForResource ........................................................................................................ 773
TagResource ................................................................................................................... 775

vii
 AWS IoT API Reference

UntagResource ............................................................................................................... 777

UpdateApplication .......................................................................................................... 779
AWS IoT Secure Tunneling ....................................................................................................... 781
CloseTunnel ................................................................................................................... 782
DescribeTunnel ............................................................................................................... 784
ListTagsForResource ........................................................................................................ 786
ListTunnels .................................................................................................................... 788
OpenTunnel ................................................................................................................... 790
RotateTunnelAccessToken ................................................................................................ 793
TagResource ................................................................................................................... 796
UntagResource ............................................................................................................... 798
Data Types .................................................................................................................................... 800
AWS IoT ................................................................................................................................ 805
AbortConfig ................................................................................................................... 810
AbortCriteria .................................................................................................................. 811
Action ........................................................................................................................... 813
ActiveViolation ............................................................................................................... 817
AddThingsToThingGroupParams ....................................................................................... 819
AggregationType ............................................................................................................ 820
AlertTarget .................................................................................................................... 821
Allowed ......................................................................................................................... 822
AssetPropertyTimestamp ................................................................................................. 823
AssetPropertyValue ......................................................................................................... 824
AssetPropertyVariant ....................................................................................................... 825
AttributePayload ............................................................................................................ 826
AuditCheckConfiguration ................................................................................................. 827
AuditCheckDetails ........................................................................................................... 828
AuditFinding .................................................................................................................. 830
AuditMitigationActionExecutionMetadata ........................................................................... 832
AuditMitigationActionsTaskMetadata ................................................................................. 834
AuditMitigationActionsTaskTarget ..................................................................................... 835
AuditNotificationTarget ................................................................................................... 836
AuditSuppression ............................................................................................................ 837
AuditTaskMetadata ......................................................................................................... 839
AuthInfo ........................................................................................................................ 840
AuthorizerConfig ............................................................................................................ 841
AuthorizerDescription ...................................................................................................... 842
AuthorizerSummary ........................................................................................................ 844
AuthResult ..................................................................................................................... 845
AwsJobAbortConfig ......................................................................................................... 846
AwsJobAbortCriteria ........................................................................................................ 847
AwsJobExecutionsRolloutConfig ........................................................................................ 849
AwsJobExponentialRolloutRate ......................................................................................... 850
AwsJobPresignedUrlConfig ............................................................................................... 851
AwsJobRateIncreaseCriteria .............................................................................................. 852
AwsJobTimeoutConfig ..................................................................................................... 853
Behavior ........................................................................................................................ 854
BehaviorCriteria .............................................................................................................. 856
BehaviorModelTrainingSummary ....................................................................................... 858
BillingGroupMetadata ...................................................................................................... 860
BillingGroupProperties .................................................................................................... 861
Bucket ........................................................................................................................... 862
BucketsAggregationType .................................................................................................. 863
CACertificate .................................................................................................................. 864
CACertificateDescription .................................................................................................. 865
Certificate ...................................................................................................................... 868
CertificateDescription ...................................................................................................... 870

viii
 AWS IoT API Reference

CertificateValidity ........................................................................................................... 873

CloudwatchAlarmAction .................................................................................................. 874
CloudwatchLogsAction .................................................................................................... 875
CloudwatchMetricAction .................................................................................................. 876
CodeSigning ................................................................................................................... 878
CodeSigningCertificateChain ............................................................................................ 879
CodeSigningSignature ..................................................................................................... 880
Configuration ................................................................................................................. 881
CustomCodeSigning ........................................................................................................ 882
Denied .......................................................................................................................... 883
Destination .................................................................................................................... 884
DetectMitigationActionExecution ...................................................................................... 885
DetectMitigationActionsTaskStatistics ................................................................................ 887
DetectMitigationActionsTaskSummary ............................................................................... 888
DetectMitigationActionsTaskTarget ................................................................................... 890
DocumentParameter ....................................................................................................... 891
DomainConfigurationSummary ......................................................................................... 893
DynamoDBAction ............................................................................................................ 894
DynamoDBv2Action ........................................................................................................ 896
EffectivePolicy ................................................................................................................ 897
ElasticsearchAction ......................................................................................................... 898
EnableIoTLoggingParams ................................................................................................. 900
ErrorInfo ........................................................................................................................ 901
ExplicitDeny ................................................................................................................... 902
ExponentialRolloutRate ................................................................................................... 903
Field ............................................................................................................................. 904
FileLocation ................................................................................................................... 905
FirehoseAction ................................................................................................................ 906
FleetMetricNameAndArn .................................................................................................. 907
GroupNameAndArn ......................................................................................................... 908
HttpAction ..................................................................................................................... 909
HttpActionHeader ........................................................................................................... 911
HttpAuthorization ........................................................................................................... 912
HttpContext ................................................................................................................... 913
HttpUrlDestinationConfiguration ...................................................................................... 914
HttpUrlDestinationProperties ........................................................................................... 915
HttpUrlDestinationSummary ............................................................................................ 916
ImplicitDeny ................................................................................................................... 917
IndexingFilter ................................................................................................................. 918
IotAnalyticsAction ........................................................................................................... 919
IotEventsAction .............................................................................................................. 920
IotSiteWiseAction ........................................................................................................... 922
IssuerCertificateIdentifier ................................................................................................. 923
Job ............................................................................................................................... 924
JobExecution .................................................................................................................. 929
JobExecutionsRetryConfig ................................................................................................ 931
JobExecutionsRolloutConfig ............................................................................................. 932
JobExecutionStatusDetails ............................................................................................... 933
JobExecutionSummary .................................................................................................... 934
JobExecutionSummaryForJob ........................................................................................... 936
JobExecutionSummaryForThing ........................................................................................ 937
JobProcessDetails ........................................................................................................... 938
JobSummary .................................................................................................................. 940
JobTemplateSummary ..................................................................................................... 942
KafkaAction ................................................................................................................... 944
KeyPair .......................................................................................................................... 945
KinesisAction .................................................................................................................. 946

ix
 AWS IoT API Reference

LambdaAction ................................................................................................................ 947

LocationAction ............................................................................................................... 948
LocationTimestamp ......................................................................................................... 950
LoggingOptionsPayload ................................................................................................... 951
LogTarget ...................................................................................................................... 952
LogTargetConfiguration ................................................................................................... 953
MachineLearningDetectionConfig ...................................................................................... 954
ManagedJobTemplateSummary ........................................................................................ 955
MetricDatum .................................................................................................................. 957
MetricDimension ............................................................................................................. 958
MetricToRetain ............................................................................................................... 959
MetricValue .................................................................................................................... 960
MitigationAction ............................................................................................................. 962
MitigationActionIdentifier ................................................................................................ 963
MitigationActionParams ................................................................................................... 964
MqttContext .................................................................................................................. 966
MqttHeaders .................................................................................................................. 967
NonCompliantResource ................................................................................................... 969
OpenSearchAction .......................................................................................................... 970
OTAUpdateFile ............................................................................................................... 971
OTAUpdateInfo ............................................................................................................... 973
OTAUpdateSummary ....................................................................................................... 976
OutgoingCertificate ........................................................................................................ 977
PercentPair .................................................................................................................... 979
Policy ............................................................................................................................ 980
PolicyVersion .................................................................................................................. 981
PolicyVersionIdentifier ..................................................................................................... 982
PresignedUrlConfig ......................................................................................................... 983
ProvisioningHook ............................................................................................................ 984
ProvisioningTemplateSummary ......................................................................................... 985
ProvisioningTemplateVersionSummary .............................................................................. 987
PublishFindingToSnsParams ............................................................................................. 988
PutAssetPropertyValueEntry ............................................................................................ 989
PutItemInput .................................................................................................................. 991
RateIncreaseCriteria ........................................................................................................ 992
RegistrationConfig .......................................................................................................... 993
RelatedResource ............................................................................................................. 994
ReplaceDefaultPolicyVersionParams .................................................................................. 995
RepublishAction .............................................................................................................. 996
ResourceIdentifier ........................................................................................................... 997
RetryCriteria ................................................................................................................... 999
RoleAliasDescription ...................................................................................................... 1000
S3Action ...................................................................................................................... 1002
S3Destination ............................................................................................................... 1003
S3Location ................................................................................................................... 1004
SalesforceAction ........................................................................................................... 1005
ScheduledAuditMetadata ............................................................................................... 1006
SchedulingConfig .......................................................................................................... 1008
SecurityProfileIdentifier ................................................................................................. 1009
SecurityProfileTarget ..................................................................................................... 1010
SecurityProfileTargetMapping ......................................................................................... 1011
ServerCertificateSummary .............................................................................................. 1012
SigningProfileParameter ................................................................................................ 1013
SigV4Authorization ....................................................................................................... 1014
SnsAction ..................................................................................................................... 1015
SqsAction ..................................................................................................................... 1016
StartSigningJobParameter ............................................................................................. 1017

x
 AWS IoT API Reference

StatisticalThreshold ....................................................................................................... 1018

Statistics ...................................................................................................................... 1019
StepFunctionsAction ...................................................................................................... 1021
Stream ........................................................................................................................ 1022
StreamFile ................................................................................................................... 1023
StreamInfo ................................................................................................................... 1024
StreamSummary ........................................................................................................... 1026
Tag ............................................................................................................................. 1027
TaskStatistics ................................................................................................................ 1028
TaskStatisticsForAuditCheck ........................................................................................... 1030
TermsAggregation ......................................................................................................... 1031
ThingAttribute .............................................................................................................. 1032
ThingConnectivity ......................................................................................................... 1034
ThingDocument ............................................................................................................ 1035
ThingGroupDocument ................................................................................................... 1037
ThingGroupIndexingConfiguration ................................................................................... 1039
ThingGroupMetadata ..................................................................................................... 1040
ThingGroupProperties ................................................................................................... 1041
ThingIndexingConfiguration ........................................................................................... 1042
ThingTypeDefinition ...................................................................................................... 1044
ThingTypeMetadata ....................................................................................................... 1045
ThingTypeProperties ..................................................................................................... 1046
TimeoutConfig .............................................................................................................. 1047
TimestreamAction ......................................................................................................... 1048
TimestreamDimension ................................................................................................... 1050
TimestreamTimestamp .................................................................................................. 1051
TlsContext ................................................................................................................... 1052
TopicRule ..................................................................................................................... 1053
TopicRuleDestination ..................................................................................................... 1055
TopicRuleDestinationConfiguration .................................................................................. 1057
TopicRuleDestinationSummary ....................................................................................... 1058
TopicRuleListItem .......................................................................................................... 1060
TopicRulePayload .......................................................................................................... 1061
TransferData ................................................................................................................ 1063
UpdateCACertificateParams ............................................................................................ 1065
UpdateDeviceCertificateParams ...................................................................................... 1066
UserProperty ................................................................................................................ 1067
ValidationError ............................................................................................................. 1068
ViolationEvent .............................................................................................................. 1069
ViolationEventAdditionalInfo .......................................................................................... 1071
ViolationEventOccurrenceRange ...................................................................................... 1072
VpcDestinationConfiguration .......................................................................................... 1073
VpcDestinationProperties ............................................................................................... 1074
VpcDestinationSummary ................................................................................................ 1075
AWS IoT data ....................................................................................................................... 1075
RetainedMessageSummary ............................................................................................. 1076
AWS IoT jobs data ................................................................................................................ 1076
JobExecution ................................................................................................................ 1078
JobExecutionState ......................................................................................................... 1081
JobExecutionSummary .................................................................................................. 1082
AWS IoT Core Device Advisor ................................................................................................. 1083
DeviceUnderTest ........................................................................................................... 1084
GroupResult ................................................................................................................. 1085
SuiteDefinitionConfiguration .......................................................................................... 1086
SuiteDefinitionInformation ............................................................................................. 1088
SuiteRunConfiguration ................................................................................................... 1090
SuiteRunInformation ..................................................................................................... 1091

xi
 AWS IoT API Reference

TestCaseRun ................................................................................................................. 1093

TestResult .................................................................................................................... 1095
AWS IoT Fleet Hub ............................................................................................................... 1095
ApplicationSummary ..................................................................................................... 1096
AWS IoT Secure Tunneling ..................................................................................................... 1097
ConnectionState ........................................................................................................... 1098
DestinationConfig ......................................................................................................... 1099
Tag ............................................................................................................................. 1100
TimeoutConfig .............................................................................................................. 1101
Tunnel ......................................................................................................................... 1102
TunnelSummary ........................................................................................................... 1104
Common Parameters ..................................................................................................................... 1106

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

• AddThingToBillingGroup (p. 17)
• AddThingToThingGroup (p. 20)
• AssociateTargetsWithJob (p. 23)
• AttachPolicy (p. 26)
• AttachPrincipalPolicy (p. 28)
• AttachSecurityProfile (p. 30)
• AttachThingPrincipal (p. 32)
• CancelAuditMitigationActionsTask (p. 34)
• CancelAuditTask (p. 36)
• CancelCertificateTransfer (p. 38)
• CancelDetectMitigationActionsTask (p. 40)
• CancelJob (p. 42)
• CancelJobExecution (p. 45)
• ClearDefaultAuthorizer (p. 48)
• ConfirmTopicRuleDestination (p. 50)
• CreateAuditSuppression (p. 52)
• CreateAuthorizer (p. 55)
• CreateBillingGroup (p. 59)
• CreateCertificateFromCsr (p. 62)
• CreateCustomMetric (p. 65)
• CreateDimension (p. 68)
• CreateDomainConfiguration (p. 71)
• CreateDynamicThingGroup (p. 75)
• CreateFleetMetric (p. 79)
• CreateJob (p. 84)
• CreateJobTemplate (p. 90)
• CreateKeysAndCertificate (p. 95)
• CreateMitigationAction (p. 98)
• CreateOTAUpdate (p. 101)
• CreatePolicy (p. 107)
• CreatePolicyVersion (p. 110)
• CreateProvisioningClaim (p. 113)
• CreateProvisioningTemplate (p. 116)
• CreateProvisioningTemplateVersion (p. 120)
• CreateRoleAlias (p. 123)
• CreateScheduledAudit (p. 126)
• CreateSecurityProfile (p. 129)
• CreateStream (p. 133)
• CreateThing (p. 137)

3
 AWS IoT API Reference

• CreateThingGroup (p. 140)

• CreateThingType (p. 143)
• CreateTopicRule (p. 146)
• CreateTopicRuleDestination (p. 155)
• DeleteAccountAuditConfiguration (p. 158)
• DeleteAuditSuppression (p. 160)
• DeleteAuthorizer (p. 162)
• DeleteBillingGroup (p. 164)
• DeleteCACertificate (p. 166)
• DeleteCertificate (p. 168)
• DeleteCustomMetric (p. 170)
• DeleteDimension (p. 172)
• DeleteDomainConfiguration (p. 174)
• DeleteDynamicThingGroup (p. 176)
• DeleteFleetMetric (p. 178)
• DeleteJob (p. 180)
• DeleteJobExecution (p. 183)
• DeleteJobTemplate (p. 186)
• DeleteMitigationAction (p. 188)
• DeleteOTAUpdate (p. 190)
• DeletePolicy (p. 192)
• DeletePolicyVersion (p. 194)
• DeleteProvisioningTemplate (p. 196)
• DeleteProvisioningTemplateVersion (p. 198)
• DeleteRegistrationCode (p. 200)
• DeleteRoleAlias (p. 202)
• DeleteScheduledAudit (p. 204)
• DeleteSecurityProfile (p. 206)
• DeleteStream (p. 208)
• DeleteThing (p. 210)
• DeleteThingGroup (p. 212)
• DeleteThingType (p. 214)
• DeleteTopicRule (p. 216)
• DeleteTopicRuleDestination (p. 218)
• DeleteV2LoggingLevel (p. 220)
• DeprecateThingType (p. 222)
• DescribeAccountAuditConfiguration (p. 224)
• DescribeAuditFinding (p. 226)
• DescribeAuditMitigationActionsTask (p. 229)
• DescribeAuditSuppression (p. 233)
• DescribeAuditTask (p. 236)
• DescribeAuthorizer (p. 239)
• DescribeBillingGroup (p. 241)
• DescribeCACertificate (p. 244)
• DescribeCertificate (p. 247)
• DescribeCustomMetric (p. 250)

4
 AWS IoT API Reference

• DescribeDefaultAuthorizer (p. 253)

• DescribeDetectMitigationActionsTask (p. 255)
• DescribeDimension (p. 258)
• DescribeDomainConfiguration (p. 261)
• DescribeEndpoint (p. 264)
• DescribeEventConfigurations (p. 266)
• DescribeFleetMetric (p. 268)
• DescribeIndex (p. 272)
• DescribeJob (p. 275)
• DescribeJobExecution (p. 278)
• DescribeJobTemplate (p. 281)
• DescribeManagedJobTemplate (p. 285)
• DescribeMitigationAction (p. 288)
• DescribeProvisioningTemplate (p. 291)
• DescribeProvisioningTemplateVersion (p. 295)
• DescribeRoleAlias (p. 298)
• DescribeScheduledAudit (p. 300)
• DescribeSecurityProfile (p. 303)
• DescribeStream (p. 307)
• DescribeThing (p. 310)
• DescribeThingGroup (p. 313)
• DescribeThingRegistrationTask (p. 317)
• DescribeThingType (p. 321)
• DetachPolicy (p. 324)
• DetachPrincipalPolicy (p. 326)
• DetachSecurityProfile (p. 328)
• DetachThingPrincipal (p. 330)
• DisableTopicRule (p. 332)
• EnableTopicRule (p. 334)
• GetBehaviorModelTrainingSummaries (p. 336)
• GetBucketsAggregation (p. 338)
• GetCardinality (p. 342)
• GetEffectivePolicies (p. 345)
• GetIndexingConfiguration (p. 348)
• GetJobDocument (p. 351)
• GetLoggingOptions (p. 353)
• GetOTAUpdate (p. 355)
• GetPercentiles (p. 359)
• GetPolicy (p. 362)
• GetPolicyVersion (p. 365)
• GetRegistrationCode (p. 368)
• GetStatistics (p. 370)
• GetTopicRule (p. 373)
• GetTopicRuleDestination (p. 381)
• GetV2LoggingOptions (p. 383)
• ListActiveViolations (p. 385)

5
 AWS IoT API Reference

• ListAttachedPolicies (p. 388)

• ListAuditFindings (p. 391)
• ListAuditMitigationActionsExecutions (p. 395)
• ListAuditMitigationActionsTasks (p. 398)
• ListAuditSuppressions (p. 401)
• ListAuditTasks (p. 404)
• ListAuthorizers (p. 407)
• ListBillingGroups (p. 410)
• ListCACertificates (p. 412)
• ListCertificates (p. 415)
• ListCertificatesByCA (p. 418)
• ListCustomMetrics (p. 421)
• ListDetectMitigationActionsExecutions (p. 423)
• ListDetectMitigationActionsTasks (p. 426)
• ListDimensions (p. 429)
• ListDomainConfigurations (p. 431)
• ListFleetMetrics (p. 434)
• ListIndices (p. 436)
• ListJobExecutionsForJob (p. 438)
• ListJobExecutionsForThing (p. 441)
• ListJobs (p. 444)
• ListJobTemplates (p. 447)
• ListManagedJobTemplates (p. 449)
• ListMetricValues (p. 451)
• ListMitigationActions (p. 454)
• ListOTAUpdates (p. 456)
• ListOutgoingCertificates (p. 459)
• ListPolicies (p. 462)
• ListPolicyPrincipals (p. 465)
• ListPolicyVersions (p. 468)
• ListPrincipalPolicies (p. 470)
• ListPrincipalThings (p. 473)
• ListProvisioningTemplates (p. 476)
• ListProvisioningTemplateVersions (p. 478)
• ListRelatedResourcesForAuditFinding (p. 481)
• ListRoleAliases (p. 484)
• ListScheduledAudits (p. 487)
• ListSecurityProfiles (p. 489)
• ListSecurityProfilesForTarget (p. 492)
• ListStreams (p. 495)
• ListTagsForResource (p. 497)
• ListTargetsForPolicy (p. 499)
• ListTargetsForSecurityProfile (p. 502)
• ListThingGroups (p. 504)
• ListThingGroupsForThing (p. 507)
• ListThingPrincipals (p. 509)

6
 AWS IoT API Reference

• ListThingRegistrationTaskReports (p. 512)

• ListThingRegistrationTasks (p. 515)
• ListThings (p. 517)
• ListThingsInBillingGroup (p. 520)
• ListThingsInThingGroup (p. 522)
• ListThingTypes (p. 524)
• ListTopicRuleDestinations (p. 527)
• ListTopicRules (p. 529)
• ListV2LoggingLevels (p. 531)
• ListViolationEvents (p. 533)
• PutVerificationStateOnViolation (p. 537)
• RegisterCACertificate (p. 539)
• RegisterCertificate (p. 543)
• RegisterCertificateWithoutCA (p. 546)
• RegisterThing (p. 549)
• RejectCertificateTransfer (p. 552)
• RemoveThingFromBillingGroup (p. 555)
• RemoveThingFromThingGroup (p. 558)
• ReplaceTopicRule (p. 561)
• SearchIndex (p. 569)
• SetDefaultAuthorizer (p. 573)
• SetDefaultPolicyVersion (p. 576)
• SetLoggingOptions (p. 578)
• SetV2LoggingLevel (p. 580)
• SetV2LoggingOptions (p. 582)
• StartAuditMitigationActionsTask (p. 584)
• StartDetectMitigationActionsTask (p. 587)
• StartOnDemandAuditTask (p. 590)
• StartThingRegistrationTask (p. 592)
• StopThingRegistrationTask (p. 595)
• TagResource (p. 597)
• TestAuthorization (p. 599)
• TestInvokeAuthorizer (p. 603)
• TransferCertificate (p. 607)
• UntagResource (p. 610)
• UpdateAccountAuditConfiguration (p. 612)
• UpdateAuditSuppression (p. 615)
• UpdateAuthorizer (p. 618)
• UpdateBillingGroup (p. 622)
• UpdateCACertificate (p. 625)
• UpdateCertificate (p. 628)
• UpdateCustomMetric (p. 631)
• UpdateDimension (p. 634)
• UpdateDomainConfiguration (p. 637)
• UpdateDynamicThingGroup (p. 640)
• UpdateEventConfigurations (p. 643)

7
 AWS IoT API Reference

• UpdateFleetMetric (p. 645)

• UpdateIndexingConfiguration (p. 649)
• UpdateJob (p. 652)
• UpdateMitigationAction (p. 656)
• UpdateProvisioningTemplate (p. 659)
• UpdateRoleAlias (p. 662)
• UpdateScheduledAudit (p. 665)
• UpdateSecurityProfile (p. 668)
• UpdateStream (p. 674)
• UpdateThing (p. 677)
• UpdateThingGroup (p. 680)
• UpdateThingGroupsForThing (p. 683)
• UpdateTopicRuleDestination (p. 686)
• ValidateSecurityProfileBehaviors (p. 689)

The following actions are supported by AWS IoT data:

• DeleteThingShadow (p. 692)

• GetRetainedMessage (p. 695)
• GetThingShadow (p. 698)
• ListNamedShadowsForThing (p. 701)
• ListRetainedMessages (p. 704)
• Publish (p. 707)
• UpdateThingShadow (p. 710)

The following actions are supported by AWS IoT jobs data:

• DescribeJobExecution (p. 713)

• GetPendingJobExecutions (p. 716)
• StartNextPendingJobExecution (p. 719)
• UpdateJobExecution (p. 722)

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

• CreateSuiteDefinition (p. 727)

• DeleteSuiteDefinition (p. 730)
• GetEndpoint (p. 732)
• GetSuiteDefinition (p. 734)
• GetSuiteRun (p. 737)
• GetSuiteRunReport (p. 741)
• ListSuiteDefinitions (p. 743)
• ListSuiteRuns (p. 745)
• ListTagsForResource (p. 748)
• StartSuiteRun (p. 750)
• StopSuiteRun (p. 753)
• TagResource (p. 755)
• UntagResource (p. 757)

8
 AWS IoT API Reference
AWS IoT

• UpdateSuiteDefinition (p. 759)

The following actions are supported by AWS IoT Fleet Hub:

• CreateApplication (p. 762)

• DeleteApplication (p. 765)
• DescribeApplication (p. 767)
• ListApplications (p. 771)
• ListTagsForResource (p. 773)
• TagResource (p. 775)
• UntagResource (p. 777)
• UpdateApplication (p. 779)

The following actions are supported by AWS IoT Secure Tunneling:

• CloseTunnel (p. 782)

• DescribeTunnel (p. 784)
• ListTagsForResource (p. 786)
• ListTunnels (p. 788)
• OpenTunnel (p. 790)
• RotateTunnelAccessToken (p. 793)
• TagResource (p. 796)
• UntagResource (p. 798)

AWS IoT
The following actions are supported by AWS IoT:

• AcceptCertificateTransfer (p. 15)

• AddThingToBillingGroup (p. 17)
• AddThingToThingGroup (p. 20)
• AssociateTargetsWithJob (p. 23)
• AttachPolicy (p. 26)
• AttachPrincipalPolicy (p. 28)
• AttachSecurityProfile (p. 30)
• AttachThingPrincipal (p. 32)
• CancelAuditMitigationActionsTask (p. 34)
• CancelAuditTask (p. 36)
• CancelCertificateTransfer (p. 38)
• CancelDetectMitigationActionsTask (p. 40)
• CancelJob (p. 42)
• CancelJobExecution (p. 45)
• ClearDefaultAuthorizer (p. 48)
• ConfirmTopicRuleDestination (p. 50)
• CreateAuditSuppression (p. 52)
• CreateAuthorizer (p. 55)

9
 AWS IoT API Reference
AWS IoT

• CreateBillingGroup (p. 59)

• CreateCertificateFromCsr (p. 62)
• CreateCustomMetric (p. 65)
• CreateDimension (p. 68)
• CreateDomainConfiguration (p. 71)
• CreateDynamicThingGroup (p. 75)
• CreateFleetMetric (p. 79)
• CreateJob (p. 84)
• CreateJobTemplate (p. 90)
• CreateKeysAndCertificate (p. 95)
• CreateMitigationAction (p. 98)
• CreateOTAUpdate (p. 101)
• CreatePolicy (p. 107)
• CreatePolicyVersion (p. 110)
• CreateProvisioningClaim (p. 113)
• CreateProvisioningTemplate (p. 116)
• CreateProvisioningTemplateVersion (p. 120)
• CreateRoleAlias (p. 123)
• CreateScheduledAudit (p. 126)
• CreateSecurityProfile (p. 129)
• CreateStream (p. 133)
• CreateThing (p. 137)
• CreateThingGroup (p. 140)
• CreateThingType (p. 143)
• CreateTopicRule (p. 146)
• CreateTopicRuleDestination (p. 155)
• DeleteAccountAuditConfiguration (p. 158)
• DeleteAuditSuppression (p. 160)
• DeleteAuthorizer (p. 162)
• DeleteBillingGroup (p. 164)
• DeleteCACertificate (p. 166)
• DeleteCertificate (p. 168)
• DeleteCustomMetric (p. 170)
• DeleteDimension (p. 172)
• DeleteDomainConfiguration (p. 174)
• DeleteDynamicThingGroup (p. 176)
• DeleteFleetMetric (p. 178)
• DeleteJob (p. 180)
• DeleteJobExecution (p. 183)
• DeleteJobTemplate (p. 186)
• DeleteMitigationAction (p. 188)
• DeleteOTAUpdate (p. 190)
• DeletePolicy (p. 192)
• DeletePolicyVersion (p. 194)
• DeleteProvisioningTemplate (p. 196)
• DeleteProvisioningTemplateVersion (p. 198)

10
 AWS IoT API Reference
AWS IoT

• DeleteRegistrationCode (p. 200)

• DeleteRoleAlias (p. 202)
• DeleteScheduledAudit (p. 204)
• DeleteSecurityProfile (p. 206)
• DeleteStream (p. 208)
• DeleteThing (p. 210)
• DeleteThingGroup (p. 212)
• DeleteThingType (p. 214)
• DeleteTopicRule (p. 216)
• DeleteTopicRuleDestination (p. 218)
• DeleteV2LoggingLevel (p. 220)
• DeprecateThingType (p. 222)
• DescribeAccountAuditConfiguration (p. 224)
• DescribeAuditFinding (p. 226)
• DescribeAuditMitigationActionsTask (p. 229)
• DescribeAuditSuppression (p. 233)
• DescribeAuditTask (p. 236)
• DescribeAuthorizer (p. 239)
• DescribeBillingGroup (p. 241)
• DescribeCACertificate (p. 244)
• DescribeCertificate (p. 247)
• DescribeCustomMetric (p. 250)
• DescribeDefaultAuthorizer (p. 253)
• DescribeDetectMitigationActionsTask (p. 255)
• DescribeDimension (p. 258)
• DescribeDomainConfiguration (p. 261)
• DescribeEndpoint (p. 264)
• DescribeEventConfigurations (p. 266)
• DescribeFleetMetric (p. 268)
• DescribeIndex (p. 272)
• DescribeJob (p. 275)
• DescribeJobExecution (p. 278)
• DescribeJobTemplate (p. 281)
• DescribeManagedJobTemplate (p. 285)
• DescribeMitigationAction (p. 288)
• DescribeProvisioningTemplate (p. 291)
• DescribeProvisioningTemplateVersion (p. 295)
• DescribeRoleAlias (p. 298)
• DescribeScheduledAudit (p. 300)
• DescribeSecurityProfile (p. 303)
• DescribeStream (p. 307)
• DescribeThing (p. 310)
• DescribeThingGroup (p. 313)
• DescribeThingRegistrationTask (p. 317)
• DescribeThingType (p. 321)
• DetachPolicy (p. 324)

11
 AWS IoT API Reference
AWS IoT

• DetachPrincipalPolicy (p. 326)

• DetachSecurityProfile (p. 328)
• DetachThingPrincipal (p. 330)
• DisableTopicRule (p. 332)
• EnableTopicRule (p. 334)
• GetBehaviorModelTrainingSummaries (p. 336)
• GetBucketsAggregation (p. 338)
• GetCardinality (p. 342)
• GetEffectivePolicies (p. 345)
• GetIndexingConfiguration (p. 348)
• GetJobDocument (p. 351)
• GetLoggingOptions (p. 353)
• GetOTAUpdate (p. 355)
• GetPercentiles (p. 359)
• GetPolicy (p. 362)
• GetPolicyVersion (p. 365)
• GetRegistrationCode (p. 368)
• GetStatistics (p. 370)
• GetTopicRule (p. 373)
• GetTopicRuleDestination (p. 381)
• GetV2LoggingOptions (p. 383)
• ListActiveViolations (p. 385)
• ListAttachedPolicies (p. 388)
• ListAuditFindings (p. 391)
• ListAuditMitigationActionsExecutions (p. 395)
• ListAuditMitigationActionsTasks (p. 398)
• ListAuditSuppressions (p. 401)
• ListAuditTasks (p. 404)
• ListAuthorizers (p. 407)
• ListBillingGroups (p. 410)
• ListCACertificates (p. 412)
• ListCertificates (p. 415)
• ListCertificatesByCA (p. 418)
• ListCustomMetrics (p. 421)
• ListDetectMitigationActionsExecutions (p. 423)
• ListDetectMitigationActionsTasks (p. 426)
• ListDimensions (p. 429)
• ListDomainConfigurations (p. 431)
• ListFleetMetrics (p. 434)
• ListIndices (p. 436)
• ListJobExecutionsForJob (p. 438)
• ListJobExecutionsForThing (p. 441)
• ListJobs (p. 444)
• ListJobTemplates (p. 447)
• ListManagedJobTemplates (p. 449)
• ListMetricValues (p. 451)

12
 AWS IoT API Reference
AWS IoT

• ListMitigationActions (p. 454)

• ListOTAUpdates (p. 456)
• ListOutgoingCertificates (p. 459)
• ListPolicies (p. 462)
• ListPolicyPrincipals (p. 465)
• ListPolicyVersions (p. 468)
• ListPrincipalPolicies (p. 470)
• ListPrincipalThings (p. 473)
• ListProvisioningTemplates (p. 476)
• ListProvisioningTemplateVersions (p. 478)
• ListRelatedResourcesForAuditFinding (p. 481)
• ListRoleAliases (p. 484)
• ListScheduledAudits (p. 487)
• ListSecurityProfiles (p. 489)
• ListSecurityProfilesForTarget (p. 492)
• ListStreams (p. 495)
• ListTagsForResource (p. 497)
• ListTargetsForPolicy (p. 499)
• ListTargetsForSecurityProfile (p. 502)
• ListThingGroups (p. 504)
• ListThingGroupsForThing (p. 507)
• ListThingPrincipals (p. 509)
• ListThingRegistrationTaskReports (p. 512)
• ListThingRegistrationTasks (p. 515)
• ListThings (p. 517)
• ListThingsInBillingGroup (p. 520)
• ListThingsInThingGroup (p. 522)
• ListThingTypes (p. 524)
• ListTopicRuleDestinations (p. 527)
• ListTopicRules (p. 529)
• ListV2LoggingLevels (p. 531)
• ListViolationEvents (p. 533)
• PutVerificationStateOnViolation (p. 537)
• RegisterCACertificate (p. 539)
• RegisterCertificate (p. 543)
• RegisterCertificateWithoutCA (p. 546)
• RegisterThing (p. 549)
• RejectCertificateTransfer (p. 552)
• RemoveThingFromBillingGroup (p. 555)
• RemoveThingFromThingGroup (p. 558)
• ReplaceTopicRule (p. 561)
• SearchIndex (p. 569)
• SetDefaultAuthorizer (p. 573)
• SetDefaultPolicyVersion (p. 576)
• SetLoggingOptions (p. 578)
• SetV2LoggingLevel (p. 580)

13
 AWS IoT API Reference
AWS IoT

• SetV2LoggingOptions (p. 582)

• StartAuditMitigationActionsTask (p. 584)
• StartDetectMitigationActionsTask (p. 587)
• StartOnDemandAuditTask (p. 590)
• StartThingRegistrationTask (p. 592)
• StopThingRegistrationTask (p. 595)
• TagResource (p. 597)
• TestAuthorization (p. 599)
• TestInvokeAuthorizer (p. 603)
• TransferCertificate (p. 607)
• UntagResource (p. 610)
• UpdateAccountAuditConfiguration (p. 612)
• UpdateAuditSuppression (p. 615)
• UpdateAuthorizer (p. 618)
• UpdateBillingGroup (p. 622)
• UpdateCACertificate (p. 625)
• UpdateCertificate (p. 628)
• UpdateCustomMetric (p. 631)
• UpdateDimension (p. 634)
• UpdateDomainConfiguration (p. 637)
• UpdateDynamicThingGroup (p. 640)
• UpdateEventConfigurations (p. 643)
• UpdateFleetMetric (p. 645)
• UpdateIndexingConfiguration (p. 649)
• UpdateJob (p. 652)
• UpdateMitigationAction (p. 656)
• UpdateProvisioningTemplate (p. 659)
• UpdateRoleAlias (p. 662)
• UpdateScheduledAudit (p. 665)
• UpdateSecurityProfile (p. 668)
• UpdateStream (p. 674)
• UpdateThing (p. 677)
• UpdateThingGroup (p. 680)
• UpdateThingGroupsForThing (p. 683)
• UpdateTopicRuleDestination (p. 686)
• ValidateSecurityProfileBehaviors (p. 689)

14
 AWS IoT API Reference
AcceptCertificateTransfer

AcceptCertificateTransfer
Service: AWS IoT

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

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

Requires permission to access the AcceptCertificateTransfer action.

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

URI Request Parameters

The request uses the following URI parameters.

certificateId (p. 15)

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

Length Constraints: Fixed length of 64.

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

Required: Yes
setAsActive (p. 15)

Specifies whether the certificate is active.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

15
 AWS IoT API Reference
AcceptCertificateTransfer

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

TransferAlreadyCompletedException

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

HTTP Status Code: 410

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

16
 AWS IoT API Reference
AddThingToBillingGroup

AddThingToBillingGroup
Service: AWS IoT

Adds a thing to a billing group.

Requires permission to access the AddThingToBillingGroup action.

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

{
"billingGroupArn": "string",
"billingGroupName": "string",
"thingArn": "string",
"thingName": "string"
}

URI Request Parameters

The request does not use any URI parameters.

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

billingGroupArn (p. 17)

The ARN of the billing group.

Type: String

Required: No
billingGroupName (p. 17)

The name of the billing group.

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

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

Type: String

Required: No
thingName (p. 17)

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

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

18
 AWS IoT API Reference
AddThingToBillingGroup

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

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

Type: Boolean

Required: No
thingArn (p. 20)

The ARN of the thing to add to a group.

Type: String

Required: No
thingGroupArn (p. 20)

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

Type: String

Required: No
thingGroupName (p. 20)

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

Type: String

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

20
 AWS IoT API Reference
AddThingToThingGroup

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

Required: No
thingName (p. 20)

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

21
 AWS IoT API Reference
AddThingToThingGroup

• AWS SDK for Java V2

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

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

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

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

When you specify a value for this parameter, AWS IoT Core sends jobs 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. 23)

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

23
 AWS IoT API Reference
AssociateTargetsWithJob

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
targets (p. 23)

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

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

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

An ARN identifying the job.

Type: String
jobId (p. 24)

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

24
 AWS IoT API Reference
AssociateTargetsWithJob

Errors
InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

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.

26
 AWS IoT API Reference
AttachPolicy

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

Requires permission to access the AttachPrincipalPolicy action.

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

URI Request Parameters

The request uses the following URI parameters.

policyName (p. 28)

The policy name.

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

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

Required: Yes
principal (p. 28)

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

28
 AWS IoT API Reference
AttachPrincipalPolicy

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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.

30
 AWS IoT API Reference
AttachSecurityProfile

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

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

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

Required: Yes
thingName (p. 32)

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.

32
 AWS IoT API Reference
AttachThingPrincipal

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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.

34
 AWS IoT API Reference
CancelAuditMitigationActionsTask

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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.

36
 AWS IoT API Reference
CancelAuditTask

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

37
 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. 552) 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. 38)

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

Length Constraints: Fixed length of 64.

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

Required: Yes

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

38
 AWS IoT API Reference
CancelCertificateTransfer

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

TransferAlreadyCompletedException

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

HTTP Status Code: 410

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

40
 AWS IoT API Reference
CancelDetectMitigationActionsTask

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

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

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

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

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

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

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

The job ARN.

Type: String
jobId (p. 43)

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

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

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

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

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

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

(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

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

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

46
 AWS IoT API Reference
CancelJobExecution

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

47
 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

48
 AWS IoT API Reference
ClearDefaultAuthorizer

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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.

50
 AWS IoT API Reference
ConfirmTopicRuleDestination

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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.

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

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

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

Required: No
expirationDate (p. 52)

The epoch timestamp in seconds at which this suppression expires.

Type: Timestamp

Required: No
resourceIdentifier (p. 52)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 997) object

Required: Yes
suppressIndefinitely (p. 52)

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.

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

54
 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. 55)

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

The ARN of the authorizer's Lambda function.

Type: String

Length Constraints: Maximum length of 2048.

Pattern: [\s\S]*

Required: Yes

55
 AWS IoT API Reference
CreateAuthorizer

enableCachingForHttp (p. 55)

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

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

Type: Boolean

Required: No
status (p. 55)

The status of the create authorizer request.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
tags (p. 55)

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

Required: No
tokenKeyName (p. 55)

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

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

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

The authorizer ARN.

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 57)

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

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

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

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

The properties of the billing group.

Type: BillingGroupProperties (p. 861) object

Required: No
tags (p. 59)

Metadata which can be used to manage the billing group.

Type: Array of Tag (p. 1027) objects

Required: No

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

The ARN of the billing group.

Type: String
billingGroupId (p. 60)

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

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

60
 AWS IoT API Reference
CreateBillingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

61
 AWS IoT API Reference
CreateCertificateFromCsr

CreateCertificateFromCsr
Service: AWS IoT

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

Note: The CSR must include a public key that is either an RSA key with a length of at least 2048 bits
or an ECC key from NIST P-256, NIST P-384, or NIST P-512 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.

Requires permission to access the CreateCertificateFromCsr action.

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

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

On Linux and OS X, the command is:

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

my-csr-directory/{}

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

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

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

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

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

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

my-csr-directory/$_}

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

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

file://@path"

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

{
"certificateSigningRequest": "string"
}

URI Request Parameters

The request uses the following URI parameters.

setAsActive (p. 62)

Specifies whether the certificate is active.

62
 AWS IoT API Reference
CreateCertificateFromCsr

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

certificateSigningRequest (p. 62)

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

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

Type: String
certificateId (p. 63)

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

The certificate data, in PEM format.

Type: String

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

Pattern: [\s\S]*

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

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

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

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

65
 AWS IoT API Reference
CreateCustomMetric

displayName (p. 65)

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

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

Metadata that can be used to manage the custom metric.

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

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

Type: String
metricName (p. 66)

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

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

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

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

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

68
 AWS IoT API Reference
CreateDimension

stringValues (p. 68)

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

Metadata that can be used to manage the dimension.

Type: Array of Tag (p. 1027) objects

Required: No
type (p. 68)

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

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

Type: String
name (p. 69)

A unique identifier for the dimension.

Type: String

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

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

69
 AWS IoT API Reference
CreateDimension

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

70
 AWS IoT API Reference
CreateDomainConfiguration

CreateDomainConfiguration
Service: AWS IoT

Creates a domain configuration.

Requires permission to access the CreateDomainConfiguration action.

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

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

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 71)

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

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 841) object

Required: No
domainName (p. 71)

The name of the domain.

71
 AWS IoT API Reference
CreateDomainConfiguration

Type: String

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

Pattern: [\s\S]*

Required: No
serverCertificateArns (p. 71)

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

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

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

Required: No
validationCertificateArn (p. 71)

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

Type: String

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

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

Required: No

72
 AWS IoT API Reference
CreateDomainConfiguration

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

The ARN of the domain configuration.

Type: String
domainConfigurationName (p. 73)

The name of the domain configuration.

Type: String

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

Pattern: [\w.-]+

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

73
 AWS IoT API Reference
CreateDomainConfiguration

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

The dynamic thing group index name.

Note
Currently one index is supported: AWS_Things.

Type: String

75
 AWS IoT API Reference
CreateDynamicThingGroup

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

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

Required: No
queryString (p. 75)

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

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

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

Type: Array of Tag (p. 1027) objects

Required: No
thingGroupProperties (p. 75)

The dynamic thing group properties.

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

76
 AWS IoT API Reference
CreateDynamicThingGroup

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

indexName (p. 76)

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

The dynamic thing group search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 76)

The dynamic thing group query version.

Type: String
thingGroupArn (p. 76)

The dynamic thing group ARN.

Type: String
thingGroupId (p. 76)

The dynamic thing group ID.

Type: String

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

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

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

77
 AWS IoT API Reference
CreateDynamicThingGroup

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

79
 AWS IoT API Reference
CreateFleetMetric

aggregationType (p. 79)

The type of the aggregation query.

Type: AggregationType (p. 820) object

Required: Yes
description (p. 79)

The fleet metric description.

Type: String

Length Constraints: Maximum length of 1024.

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

Required: No
indexName (p. 79)

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

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

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 79)

The query version.

Type: String

Required: No
tags (p. 79)

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

Type: Array of Tag (p. 1027) objects

80
 AWS IoT API Reference
CreateFleetMetric

Required: No
unit (p. 79)

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

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

Type: String
metricName (p. 81)

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.

81
 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

82
 AWS IoT API Reference
CreateFleetMetric

• AWS SDK for JavaScript

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

83
 AWS IoT API Reference
CreateJob

CreateJob
Service: AWS IoT

Creates a job.

Requires permission to access the CreateJob action.

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

{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"description": "string",
"document": "string",
"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",
"startTime": "string"
},
"tags": [
{
"Key": "string",
"Value": "string"

84
 AWS IoT API Reference
CreateJob

}
],
"targets": [ "string" ],
"targetSelection": "string",
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

URI Request Parameters

The request uses the following URI parameters.

jobId (p. 84)

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

Allows you to create the criteria to abort a job.

Type: AbortConfig (p. 810) object

Required: No
description (p. 84)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
document (p. 84)

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

Parameters of an AWS managed template that you can specify to create the job document.

85
 AWS IoT API Reference
CreateJob

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

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

Type: String

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

Required: No
jobExecutionsRetryConfig (p. 84)

Allows you to create the criteria to retry a job.

Type: JobExecutionsRetryConfig (p. 931) object

Required: No
jobExecutionsRolloutConfig (p. 84)

Allows you to create a staged rollout of the job.

Type: JobExecutionsRolloutConfig (p. 932) object

Required: No
jobTemplateArn (p. 84)

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

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

86
 AWS IoT API Reference
CreateJob

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

Configuration information for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 983) object

Required: No
schedulingConfig (p. 84)

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

Required: No
tags (p. 84)

Metadata which can be used to manage the job.

Type: Array of Tag (p. 1027) objects

Required: No
targets (p. 84)

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.

Required: Yes
targetSelection (p. 84)

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

87
 AWS IoT API Reference
CreateJob

Required: No
timeoutConfig (p. 84)

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. 1047) 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. 88)

The job description.

Type: String

Length Constraints: Maximum length of 2028.

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

The job ARN.

Type: String
jobId (p. 88)

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.

88
 AWS IoT API Reference
CreateJob

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

89
 AWS IoT API Reference
CreateJobTemplate

CreateJobTemplate
Service: AWS IoT

Creates a job template.

Requires permission to access the CreateJobTemplate action.

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

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

90
 AWS IoT API Reference
CreateJobTemplate

URI Request Parameters

The request uses the following URI parameters.

jobTemplateId (p. 90)

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

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

Type: AbortConfig (p. 810) object

Required: No
description (p. 90)

A description of the job document.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: Yes
document (p. 90)

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

Type: String

Length Constraints: Maximum length of 32768.

Required: No
documentSource (p. 90)

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

91
 AWS IoT API Reference
CreateJobTemplate

Type: String

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

Required: No
jobArn (p. 90)

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

Type: String

Required: No
jobExecutionsRetryConfig (p. 90)

Allows you to create the criteria to retry a job.

Type: JobExecutionsRetryConfig (p. 931) object

Required: No
jobExecutionsRolloutConfig (p. 90)

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 932) object

Required: No
presignedUrlConfig (p. 90)

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 983) object

Required: No
tags (p. 90)

Metadata that can be used to manage the job template.

Type: Array of Tag (p. 1027) objects

Required: No
timeoutConfig (p. 90)

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

Required: No

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

{
"jobTemplateArn": "string",
"jobTemplateId": "string"

92
 AWS IoT API Reference
CreateJobTemplate

Response Elements
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. 92)

The ARN of the job template.

Type: String

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

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

The unique identifier of the job template.

Type: String

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

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

Errors
ConflictException

A resource with the same name already exists.

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

93
 AWS IoT API Reference
CreateJobTemplate

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

The ARN of the certificate.

Type: String

95
 AWS IoT API Reference
CreateKeysAndCertificate

certificateId (p. 95)

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

The certificate data, in PEM format.

Type: String

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

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

The generated key pair.

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

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

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

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

98
 AWS IoT API Reference
CreateMitigationAction

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

actionParams (p. 98)

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

Type: MitigationActionParams (p. 964) object

Required: Yes
roleArn (p. 98)

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

Metadata that can be used to manage the mitigation action.

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

The ARN for the new mitigation action.

Type: String
actionId (p. 99)

A unique identifier for the new mitigation action.

Type: String

99
 AWS IoT API Reference
CreateMitigationAction

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

The ID of the OTA update to be created.

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

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

Required: Yes

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

additionalParameters (p. 101)

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

102
 AWS IoT API Reference
CreateOTAUpdate

Type: String to string map

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

Value Pattern: [\s\S]*

Required: No
awsJobAbortConfig (p. 101)

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

Type: AwsJobAbortConfig (p. 846) object

Required: No
awsJobExecutionsRolloutConfig (p. 101)

Configuration for the rollout of OTA updates.

Type: AwsJobExecutionsRolloutConfig (p. 849) object

Required: No
awsJobPresignedUrlConfig (p. 101)

Configuration information for pre-signed URLs.

Type: AwsJobPresignedUrlConfig (p. 851) object

Required: No
awsJobTimeoutConfig (p. 101)

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

Required: No
description (p. 101)

The description of the OTA update.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 101)

The files to be streamed by the OTA update.

Type: Array of OTAUpdateFile (p. 971) objects

Array Members: Minimum number of 1 item.

Required: Yes
protocols (p. 101)

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.

103
 AWS IoT API Reference
CreateOTAUpdate

Type: Array of strings

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

Valid Values: MQTT | HTTP

Required: No
roleArn (p. 101)

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

Metadata which can be used to manage updates.

Type: Array of Tag (p. 1027) objects

Required: No
targets (p. 101)

The devices targeted to receive OTA updates.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: Yes
targetSelection (p. 101)

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

Type: String

Valid Values: CONTINUOUS | SNAPSHOT

Required: No

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

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

104
 AWS IoT API Reference
CreateOTAUpdate

Response Elements
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. 104)

The AWS IoT job ARN associated with the OTA update.

Type: String
awsIotJobId (p. 104)

The AWS IoT job ID associated with the OTA update.

Type: String
otaUpdateArn (p. 104)

The OTA update ARN.

Type: String
otaUpdateId (p. 104)

The OTA update ID.

Type: String

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

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

The OTA update status.

Type: String

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

105
 AWS IoT API Reference
CreateOTAUpdate

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

106
 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. 107)

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

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

Metadata which can be used to manage the policy.

107
 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. 1027) 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. 108)

The policy ARN.

Type: String
policyDocument (p. 108)

The JSON document that describes the policy.

Type: String

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

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

The policy name.

Type: String

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

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

The policy version ID.

Type: String

Pattern: [0-9]+

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

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

The policy name.

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

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

Required: Yes
setAsDefault (p. 110)

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

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

110
 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. 111)

Specifies whether the policy version is the default.

Type: Boolean
policyArn (p. 111)

The policy ARN.

Type: String
policyDocument (p. 111)

The JSON document that describes the policy.

Type: String

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

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

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

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

112
 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. 113)

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

The ID of the certificate.

Type: String

Length Constraints: Fixed length of 64.

113
 AWS IoT API Reference
CreateProvisioningClaim

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

The provisioning claim certificate.

Type: String

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

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

The provisioning claim expiration time.

Type: Timestamp
keyPair (p. 113)

The provisioning claim key pair.

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

114
 AWS IoT API Reference
CreateProvisioningClaim

• AWS Command Line Interface

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

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

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

True to enable the provisioning template, otherwise false.

Type: Boolean

Required: No

116
 AWS IoT API Reference
CreateProvisioningTemplate

preProvisioningHook (p. 116)

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

Required: No
provisioningRoleArn (p. 116)

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

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

Required: No
templateBody (p. 116)

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

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

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

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

The default version of the provisioning template.

Type: Integer
templateArn (p. 118)

The ARN that identifies the provisioning template.

Type: String
templateName (p. 118)

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

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

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

Sets a fleet provision template version as the default version.

templateName (p. 120)

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

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

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

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

Type: Boolean
templateArn (p. 120)

The ARN that identifies the provisioning template.

Type: String
templateName (p. 120)

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

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.

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

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

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

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

The role ARN.

123
 AWS IoT API Reference
CreateRoleAlias

Type: String

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

Required: Yes
tags (p. 123)

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. 1027) 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. 124)

The role alias.

Type: String

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

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

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

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

125
 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. 126)

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

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

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.

126
 AWS IoT API Reference
CreateScheduledAudit

Type: String

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

Required: No
frequency (p. 126)

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

Metadata that can be used to manage the scheduled audit.

Type: Array of Tag (p. 1027) objects

Required: No
targetCheckNames (p. 126)

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

The ARN of the scheduled audit.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

127
 AWS IoT API Reference
CreateScheduledAudit

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

128
 AWS IoT API Reference
CreateSecurityProfile

CreateSecurityProfile
Service: AWS IoT

Creates a Device Defender security profile.

Requires permission to access the CreateSecurityProfile action.

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

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

129
 AWS IoT API Reference
CreateSecurityProfile

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

URI Request Parameters

The request uses the following URI parameters.

securityProfileName (p. 129)

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

This parameter has been deprecated.

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

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

Required: No
alertTargets (p. 129)

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

Valid Keys: SNS

Required: No
behaviors (p. 129)

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

Type: Array of Behavior (p. 854) objects

130
 AWS IoT API Reference
CreateSecurityProfile

Array Members: Maximum number of 100 items.

Required: No
securityProfileDescription (p. 129)

A description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

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

Required: No
tags (p. 129)

Metadata that can be used to manage the security profile.

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

The ARN of the security profile.

Type: String
securityProfileName (p. 131)

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.

131
 AWS IoT API Reference
CreateSecurityProfile

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

A description of the stream.

Type: String

133
 AWS IoT API Reference
CreateStream

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 133)

The files to stream.

Type: Array of StreamFile (p. 1023) objects

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

Required: Yes
roleArn (p. 133)

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

Metadata which can be used to manage streams.

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

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

134
 AWS IoT API Reference
CreateStream

streamArn (p. 134)

The stream ARN.

Type: String
streamId (p. 134)

The stream ID.

Type: String

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

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

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.

135
 AWS IoT API Reference
CreateStream

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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

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

Type: AttributePayload (p. 826) object

137
 AWS IoT API Reference
CreateThing

Required: No
billingGroupName (p. 137)

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

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

The ARN of the new thing.

Type: String
thingId (p. 138)

The thing ID.

Type: String
thingName (p. 138)

The name of the new thing.

Type: String

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

138
 AWS IoT API Reference
CreateThing

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

139
 AWS IoT API Reference
CreateThingGroup

CreateThingGroup
Service: AWS IoT

Create a thing group.

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

Requires permission to access the CreateThingGroup action.

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

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

URI Request Parameters

The request uses the following URI parameters.

thingGroupName (p. 140)

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

The name of the parent thing group.

Type: String

140
 AWS IoT API Reference
CreateThingGroup

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

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

Required: No
tags (p. 140)

Metadata which can be used to manage the thing group.

Type: Array of Tag (p. 1027) objects

Required: No
thingGroupProperties (p. 140)

The thing group properties.

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

The thing group ARN.

Type: String
thingGroupId (p. 141)

The thing group ID.

Type: String

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

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

The thing group name.

Type: String

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

141
 AWS IoT API Reference
CreateThingGroup

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

Metadata which can be used to manage the thing type.

Type: Array of Tag (p. 1027) objects

Required: No
thingTypeProperties (p. 143)

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

Required: No

143
 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. 144)

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

Type: String
thingTypeId (p. 144)

The thing type ID.

Type: String
thingTypeName (p. 144)

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.

144
 AWS IoT API Reference
CreateThingType

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

145
 AWS IoT API Reference
CreateTopicRule

CreateTopicRule
Service: AWS IoT

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

Requires permission to access the CreateTopicRule action.

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

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

146
 AWS IoT API Reference
CreateTopicRule

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

147
 AWS IoT API Reference
CreateTopicRule

"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"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},

148
 AWS IoT API Reference
CreateTopicRule

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

149
 AWS IoT API Reference
CreateTopicRule

"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"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"

150
 AWS IoT API Reference
CreateTopicRule

},
"destinationArn": "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"
},
"sqs": {

151
 AWS IoT API Reference
CreateTopicRule

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

The name of the rule.

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

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

Required: Yes
tags (p. 146)

Metadata which can be used to manage the topic rule.

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

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

topicRulePayload (p. 146)

The rule payload.

Type: TopicRulePayload (p. 1061) object

152
 AWS IoT API Reference
CreateTopicRule

Required: Yes

Response Syntax
HTTP/1.1 200

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

Errors
ConflictingResourceUpdateException

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

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource already exists.

HTTP Status Code: 409

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

SqlParseException

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

HTTP Status Code: 400

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

• AWS Command Line Interface

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

153
 AWS IoT API Reference
CreateTopicRule

• AWS SDK for JavaScript

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

154
 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. 155)

The topic rule destination configuration.

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

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

The topic rule destination.

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

156
 AWS IoT API Reference
CreateTopicRuleDestination

• AWS SDK for Go

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

157
 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. 158)

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

158
 AWS IoT API Reference
DeleteAccountAuditConfiguration

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

• AWS Command Line Interface

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

159
 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. 160)

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

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 997) object

Required: Yes

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

161
 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. 162)

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

162
 AWS IoT API Reference
DeleteAuthorizer

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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

164
 AWS IoT API Reference
DeleteBillingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

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

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

166
 AWS IoT API Reference
DeleteCACertificate

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

167
 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. 324) action to detach all policies. Next, use the
UpdateCertificate (p. 628) 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. 168)

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

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.

168
 AWS IoT API Reference
DeleteCertificate

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

170
 AWS IoT API Reference
DeleteCustomMetric

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

172
 AWS IoT API Reference
DeleteDimension

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

• AWS Command Line Interface

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

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

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

174
 AWS IoT API Reference
DeleteDomainConfiguration

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

The expected version of the dynamic thing group to delete.

thingGroupName (p. 176)

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

176
 AWS IoT API Reference
DeleteDynamicThingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

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

The expected version of the fleet metric to delete.

metricName (p. 178)

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

178
 AWS IoT API Reference
DeleteFleetMetric

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

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

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

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

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

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

$aws/things/THING_NAME/jobs/JOB_ID/notify-namespace-NAMESPACE_ID/
Note
The namespaceId feature is in public preview.

180
 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

181
 AWS IoT API Reference
DeleteJob

• AWS SDK for C++

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

182
 AWS IoT API Reference
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. 183)

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

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

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

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

183
 AWS IoT API Reference
DeleteJobExecution

thingName (p. 183)

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:

184
 AWS IoT API Reference
DeleteJobExecution

• AWS Command Line Interface

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

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

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

186
 AWS IoT API Reference
DeleteJobTemplate

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

188
 AWS IoT API Reference
DeleteMitigationAction

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

• AWS Command Line Interface

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

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

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

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

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

190
 AWS IoT API Reference
DeleteOTAUpdate

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

191
 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. 194) action to delete all non-default versions of the
policy; use the DetachPolicy (p. 324) 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. 192)

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.

192
 AWS IoT API Reference
DeletePolicy

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

The name of the policy.

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

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

Required: Yes
policyVersionId (p. 194)

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

194
 AWS IoT API Reference
DeletePolicyVersion

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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.

196
 AWS IoT API Reference
DeleteProvisioningTemplate

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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.

198
 AWS IoT API Reference
DeleteProvisioningTemplateVersion

HTTP Status Code: 409

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

199
 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

200
 AWS IoT API Reference
DeleteRegistrationCode

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

• AWS Command Line Interface

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

201
 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. 202)

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

202
 AWS IoT API Reference
DeleteRoleAlias

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

203
 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. 204)

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

204
 AWS IoT API Reference
DeleteScheduledAudit

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

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

206
 AWS IoT API Reference
DeleteSecurityProfile

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

207
 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. 208)

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

208
 AWS IoT API Reference
DeleteStream

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

209
 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. 210)

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

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.

210
 AWS IoT API Reference
DeleteThing

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

211
 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. 212)

The expected version of the thing group to delete.

thingGroupName (p. 212)

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

212
 AWS IoT API Reference
DeleteThingGroup

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

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

HTTP Status Code: 409

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

• AWS Command Line Interface

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

213
 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. 222), then remove
any associated things by calling UpdateThing (p. 677) to change the thing type on any associated thing,
and finally use DeleteThingType (p. 214) 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. 214)

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

214
 AWS IoT API Reference
DeleteThingType

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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.

216
 AWS IoT API Reference
DeleteTopicRule

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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.

218
 AWS IoT API Reference
DeleteTopicRuleDestination

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

Required: Yes
targetType (p. 220)

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

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

220
 AWS IoT API Reference
DeleteV2LoggingLevel

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

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

• AWS Command Line Interface

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

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

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

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.

222
 AWS IoT API Reference
DeprecateThingType

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

Which audit checks are enabled and disabled for this account.

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

auditNotificationTargetConfigurations (p. 224)

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

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

224
 AWS IoT API Reference
DescribeAccountAuditConfiguration

Valid Keys: SNS

roleArn (p. 224)

The ARN of the role that grants permission to AWS IoT to access information about your devices,
policies, certificates, and other items as required when performing an audit.

On the first call to UpdateAccountAuditConfiguration, this parameter is required.

Type: String

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

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

The findings (results) of the audit.

Type: AuditFinding (p. 830) object

Errors
InternalFailureException

An unexpected error has occurred.

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

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

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

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

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

Type: Array of MitigationAction (p. 962) objects

auditCheckToActionsMapping (p. 229)

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

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

Type: Timestamp
startTime (p. 229)

The date and time when the task was started.

Type: Timestamp

230
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

target (p. 229)

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

taskStatistics (p. 229)

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

taskStatus (p. 229)

The current status of the task.

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

231
 AWS IoT API Reference
DescribeAuditMitigationActionsTask

• AWS SDK for Ruby V3

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

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

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 997) object

Required: Yes

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

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

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

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

The epoch timestamp in seconds at which this suppression expires.

Type: Timestamp
resourceIdentifier (p. 234)

Information that identifies the noncompliant resource.

234
 AWS IoT API Reference
DescribeAuditSuppression

Type: ResourceIdentifier (p. 997) object

suppressIndefinitely (p. 234)

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

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

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

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

Detailed information about each check performed during this audit.

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

scheduledAuditName (p. 236)

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

The time the audit started.

Type: Timestamp
taskStatistics (p. 236)

Statistical information about the audit.

Type: TaskStatistics (p. 1028) object

taskStatus (p. 236)

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

Type: String

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

taskType (p. 236)

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.

237
 AWS IoT API Reference
DescribeAuditTask

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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.

239
 AWS IoT API Reference
DescribeAuthorizer

authorizerDescription (p. 239)

The authorizer description.

Type: AuthorizerDescription (p. 842) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

The ARN of the billing group.

241
 AWS IoT API Reference
DescribeBillingGroup

Type: String
billingGroupId (p. 241)

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

Additional information about the billing group.

Type: BillingGroupMetadata (p. 860) object

billingGroupName (p. 241)

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

The properties of the billing group.

Type: BillingGroupProperties (p. 861) object

version (p. 241)

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

242
 AWS IoT API Reference
DescribeBillingGroup

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

• AWS Command Line Interface

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

243
 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. 244)

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

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

The CA certificate description.

Type: CACertificateDescription (p. 865) object

registrationConfig (p. 244)

Information about the registration configuration.

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

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

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

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

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

The description of the certificate.

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

248
 AWS IoT API Reference
DescribeCertificate

• AWS SDK for Go

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

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

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

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

Type: Timestamp

250
 AWS IoT API Reference
DescribeCustomMetric

displayName (p. 250)

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

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

Type: Timestamp
metricArn (p. 250)

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

Type: String
metricName (p. 250)

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

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

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

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

The default authorizer's description.

Type: AuthorizerDescription (p. 842) object

Errors
InternalFailureException

An unexpected error has occurred.

253
 AWS IoT API Reference
DescribeDefaultAuthorizer

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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

The description of a task.

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

256
 AWS IoT API Reference
DescribeDetectMitigationActionsTask

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

The Amazon Resource Name (ARN) for the dimension.

Type: String

258
 AWS IoT API Reference
DescribeDimension

creationDate (p. 258)

The date the dimension was created.

Type: Timestamp
lastModifiedDate (p. 258)

The date the dimension was last modified.

Type: Timestamp
name (p. 258)

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

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

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

259
 AWS IoT API Reference
DescribeDimension

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

• AWS Command Line Interface

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

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

The name of the domain configuration.

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

Pattern: [\w.:-]+

Required: Yes

Request Body
The request does not have a request body.

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

{
"authorizerConfig": {
"allowAuthorizerOverride": boolean,
"defaultAuthorizerName": "string"
},
"domainConfigurationArn": "string",
"domainConfigurationName": "string",
"domainConfigurationStatus": "string",
"domainName": "string",
"domainType": "string",
"lastStatusChangeDate": number,
"serverCertificates": [
{
"serverCertificateArn": "string",
"serverCertificateStatus": "string",
"serverCertificateStatusDetail": "string"
}
],
"serviceType": "string"
}

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

261
 AWS IoT API Reference
DescribeDomainConfiguration

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

authorizerConfig (p. 261)

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 841) object

domainConfigurationArn (p. 261)

The ARN of the domain configuration.

Type: String
domainConfigurationName (p. 261)

The name of the domain configuration.

Type: String

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

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

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

Type: String

Valid Values: ENABLED | DISABLED

domainName (p. 261)

The name of the domain.

Type: String

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

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

The type of the domain.

Type: String

Valid Values: ENDPOINT | AWS_MANAGED | CUSTOMER_MANAGED

lastStatusChangeDate (p. 261)

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

Type: Timestamp
serverCertificates (p. 261)

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

Type: Array of ServerCertificateSummary (p. 1012) objects

serviceType (p. 261)

The type of service delivered by the endpoint.

Type: String

262
 AWS IoT API Reference
DescribeDomainConfiguration

Valid Values: DATA | CREDENTIAL_PROVIDER | JOBS

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

The endpoint type. Valid endpoint types include:

• iot:Data - Returns a VeriSign signed data endpoint.
• iot:Data-ATS - Returns an ATS signed data endpoint.
• iot:CredentialProvider - Returns an AWS IoT credentials provider API endpoint.
• iot:Jobs - Returns an AWS IoT device management Jobs API endpoint.

We strongly recommend that customers use the newer iot:Data-ATS endpoint type to avoid
issues related to the widespread distrust of Symantec certificate authorities.

Length Constraints: Maximum length of 128.

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

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

Type: String

264
 AWS IoT API Reference
DescribeEndpoint

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

265
 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. 266)

The creation date of the event configuration.

Type: Timestamp
eventConfigurations (p. 266)

The event configurations.

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

The date the event configurations were last modified.

266
 AWS IoT API Reference
DescribeEventConfigurations

Type: Timestamp

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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.

268
 AWS IoT API Reference
DescribeFleetMetric

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

aggregationField (p. 268)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

aggregationType (p. 268)

The type of the aggregation query.

Type: AggregationType (p. 820) object

creationDate (p. 268)

The date when the fleet metric is created.

Type: Timestamp
description (p. 268)

The fleet metric description.

Type: String

Length Constraints: Maximum length of 1024.

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

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

The date when the fleet metric is last modified.

Type: Timestamp
metricArn (p. 268)

The ARN of the fleet metric to describe.

Type: String
metricName (p. 268)

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

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

269
 AWS IoT API Reference
DescribeFleetMetric

Type: Integer

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

queryString (p. 268)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 268)

The query version.

Type: String
unit (p. 268)

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

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.

270
 AWS IoT API Reference
DescribeFleetMetric

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

The index name.

Type: String

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

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

272
 AWS IoT API Reference
DescribeIndex

indexStatus (p. 272)

The index status.

Type: String

Valid Values: ACTIVE | BUILDING | REBUILDING

schema (p. 272)

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:

273
 AWS IoT API Reference
DescribeIndex

• AWS Command Line Interface

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

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

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

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

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

Required: Yes

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",
"documentParameters": {
"string" : "string"
},
"forceCanceled": boolean,
"isConcurrent": boolean,
"jobArn": "string",

275
 AWS IoT API Reference
DescribeJob

"jobExecutionsRetryConfig": {
"criteriaList": [
{
"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",
"schedulingConfig": {
"endBehavior": "string",
"endTime": "string",
"startTime": "string"
},
"status": "string",
"targets": [ "string" ],
"targetSelection": "string",
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
}

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

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

documentSource (p. 275)

An S3 link to the job document.

Type: String

276
 AWS IoT API Reference
DescribeJob

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

job (p. 275)

Information about the job.

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

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

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

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

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,

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

Information about the job execution.

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

279
 AWS IoT API Reference
DescribeJobExecution

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

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

The unique identifier of the job template.

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

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

Required: Yes

Request Body
The request does not have a request body.

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

{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"createdAt": number,
"description": "string",
"document": "string",
"documentSource": "string",
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,

281
 AWS IoT API Reference
DescribeJobTemplate

"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobTemplateArn": "string",
"jobTemplateId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}

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

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

abortConfig (p. 281)

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

Type: AbortConfig (p. 810) object

createdAt (p. 281)

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

Type: Timestamp
description (p. 281)

A description of the job template.

Type: String

Length Constraints: Maximum length of 2028.

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

The job document.

Type: String

Length Constraints: Maximum length of 32768.

documentSource (p. 281)

An S3 link to the job document.

Type: String

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

jobExecutionsRetryConfig (p. 281)

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

282
 AWS IoT API Reference
DescribeJobTemplate

Type: JobExecutionsRetryConfig (p. 931) object

jobExecutionsRolloutConfig (p. 281)

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 932) object

jobTemplateArn (p. 281)

The ARN of the job template.

Type: String

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

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

The unique identifier of the job template.

Type: String

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

Pattern: [a-zA-Z0-9_-]+
presignedUrlConfig (p. 281)

Configuration for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 983) object

timeoutConfig (p. 281)

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

283
 AWS IoT API Reference
DescribeJobTemplate

HTTP Status Code: 400

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

• AWS Command Line Interface

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

284
 AWS IoT API Reference
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. 285)

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

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.

285
 AWS IoT API Reference
DescribeManagedJobTemplate

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

description (p. 285)

The unique description of a managed template.

Type: String

Length Constraints: Maximum length of 2028.

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

The document schema for a managed job template.

Type: String

Length Constraints: Maximum length of 32768.

documentParameters (p. 285)

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

environments (p. 285)

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

Type: Array of strings

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

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

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

The version for a managed template.

Type: String

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

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

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

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"

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

The ARN that identifies this migration action.

Type: String
actionId (p. 288)

A unique identifier for this action.

Type: String
actionName (p. 288)

The friendly name that uniquely identifies the mitigation action.

Type: String

Length Constraints: Maximum length of 128.

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

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

Type: MitigationActionParams (p. 964) object

actionType (p. 288)

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

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

Type: Timestamp
lastModifiedDate (p. 288)

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

Type: Timestamp

289
 AWS IoT API Reference
DescribeMitigationAction

roleArn (p. 288)

The ARN of the IAM role used to apply this action.

Type: String

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

290
 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. 291)

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.

291
 AWS IoT API Reference
DescribeProvisioningTemplate

creationDate (p. 291)

The date when the provisioning template was created.

Type: Timestamp
defaultVersionId (p. 291)

The default fleet template version ID.

Type: Integer
description (p. 291)

The description of the provisioning template.

Type: String

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

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

True if the provisioning template is enabled, otherwise false.

Type: Boolean
lastModifiedDate (p. 291)

The date when the provisioning template was last modified.

Type: Timestamp
preProvisioningHook (p. 291)

Gets information about a pre-provisioned hook.

Type: ProvisioningHook (p. 984) object

provisioningRoleArn (p. 291)

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

The ARN of the provisioning template.

Type: String
templateBody (p. 291)

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

The name of the provisioning template.

292
 AWS IoT API Reference
DescribeProvisioningTemplate

Type: String

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

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

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

293
 AWS IoT API Reference
DescribeProvisioningTemplate

• AWS SDK for Ruby V3

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

The template name.

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

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

Required: Yes
versionId (p. 295)

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

The date when the provisioning template version was created.

295
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

Type: Timestamp
isDefaultVersion (p. 295)

True if the provisioning template version is the default version.

Type: Boolean
templateBody (p. 295)

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

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

296
 AWS IoT API Reference
DescribeProvisioningTemplateVersion

• AWS SDK for Go

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

297
 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. 298)

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

The role alias description.

298
 AWS IoT API Reference
DescribeRoleAlias

Type: RoleAliasDescription (p. 1000) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

299
 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. 300)

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

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

300
 AWS IoT API Reference
DescribeScheduledAudit

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

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

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

The ARN of the scheduled audit.

Type: String
scheduledAuditName (p. 300)

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

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

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

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

The name of the security profile whose information you want to get.

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

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

Required: Yes

Request Body
The request does not have a request body.

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

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,

303
 AWS IoT API Reference
DescribeSecurityProfile

"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"creationDate": number,
"lastModifiedDate": number,
"securityProfileArn": "string",
"securityProfileDescription": "string",
"securityProfileName": "string",
"version": number
}

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

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

additionalMetricsToRetain (p. 303)

This parameter has been deprecated.

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

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

alertTargets (p. 303)

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

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

Valid Keys: SNS

304
 AWS IoT API Reference
DescribeSecurityProfile

behaviors (p. 303)

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

Type: Array of Behavior (p. 854) objects

Array Members: Maximum number of 100 items.

creationDate (p. 303)

The time the security profile was created.

Type: Timestamp
lastModifiedDate (p. 303)

The time the security profile was last modified.

Type: Timestamp
securityProfileArn (p. 303)

The ARN of the security profile.

Type: String
securityProfileDescription (p. 303)

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

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

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

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

305
 AWS IoT API Reference
DescribeSecurityProfile

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

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

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

Information about the stream.

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

308
 AWS IoT API Reference
DescribeStream

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

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

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

The thing attributes.

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

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

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

The ARN of the thing to describe.

Type: String
thingId (p. 310)

The ID of the thing to describe.

Type: String
thingName (p. 310)

The name of the thing.

Type: String

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

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

The thing type name.

Type: String

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

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

The current version of the thing record in the registry.

311
 AWS IoT API Reference
DescribeThing

Note
To avoid unintentional changes to the information in the registry, you can pass the version
information in the expectedVersion parameter of the UpdateThing and DeleteThing
calls.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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

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

The dynamic thing group search query string.

Type: String

Length Constraints: Minimum length of 1.

queryVersion (p. 313)

The dynamic thing group query version.

Type: String
status (p. 313)

The dynamic thing group status.

Type: String

Valid Values: ACTIVE | BUILDING | REBUILDING

thingGroupArn (p. 313)

The thing group ARN.

Type: String
thingGroupId (p. 313)

The thing group ID.

Type: String

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

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

Thing group metadata.

Type: ThingGroupMetadata (p. 1040) object

314
 AWS IoT API Reference
DescribeThingGroup

thingGroupName (p. 313)

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

The thing group properties.

Type: ThingGroupProperties (p. 1041) object

version (p. 313)

The version of the thing group.

Type: Long

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

315
 AWS IoT API Reference
DescribeThingGroup

• AWS SDK for Ruby V3

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

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

The task creation date.

317
 AWS IoT API Reference
DescribeThingRegistrationTask

Type: Timestamp
failureCount (p. 317)

The number of things that failed to be provisioned.

Type: Integer
inputFileBucket (p. 317)

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

The input file key.

Type: String

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

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

The date when the task was last modified.

Type: Timestamp
message (p. 317)

The message.

Type: String

Length Constraints: Maximum length of 2048.

percentageProgress (p. 317)

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

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

The status of the bulk thing provisioning task.

Type: String

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

successCount (p. 317)

The number of things successfully provisioned.

318
 AWS IoT API Reference
DescribeThingRegistrationTask

Type: Integer
taskId (p. 317)

The task ID.

Type: String

Length Constraints: Maximum length of 40.

templateBody (p. 317)

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

319
 AWS IoT API Reference
DescribeThingRegistrationTask

• AWS SDK for JavaScript

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

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

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.

321
 AWS IoT API Reference
DescribeThingType

thingTypeArn (p. 321)

The thing type ARN.

Type: String
thingTypeId (p. 321)

The thing type ID.

Type: String
thingTypeMetadata (p. 321)

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

thingTypeName (p. 321)

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

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

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

322
 AWS IoT API Reference
DescribeThingType

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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.

324
 AWS IoT API Reference
DetachPolicy

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

The name of the policy to detach.

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

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

Required: Yes
principal (p. 326)

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.

326
 AWS IoT API Reference
DetachPrincipalPolicy

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

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.

328
 AWS IoT API Reference
DetachSecurityProfile

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

329
 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. 330)

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

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

330
 AWS IoT API Reference
DetachThingPrincipal

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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.

332
 AWS IoT API Reference
DisableTopicRule

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

333
 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. 334)

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.

334
 AWS IoT API Reference
EnableTopicRule

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

The token for the next set of results.

securityProfileName (p. 336)

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

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

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

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

Type: Array of BehaviorModelTrainingSummary (p. 858) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

The aggregation field.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
bucketsAggregationType (p. 338)

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

Type: BucketsAggregationType (p. 863) object

Required: Yes
indexName (p. 338)

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

338
 AWS IoT API Reference
GetBucketsAggregation

queryString (p. 338)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 338)

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

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

totalCount (p. 339)

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

Type: Integer

Errors
IndexNotReadyException

The index is not ready.

339
 AWS IoT API Reference
GetBucketsAggregation

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

340
AWS IoT API Reference
GetBucketsAggregation

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

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 342)

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

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 342)

The query version.

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

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.

343
 AWS IoT API Reference
GetCardinality

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

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

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

The Cognito identity pool ID.

Type: String

Required: No
principal (p. 345)

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

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

The effective policies.

Type: Array of EffectivePolicy (p. 897) 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.

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

347
 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": {
"namedShadowNames": [ "string" ]
},
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"namedShadowIndexingMode": "string",
"thingConnectivityIndexingMode": "string",

348
 AWS IoT API Reference
GetIndexingConfiguration

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

The index configuration.

Type: ThingGroupIndexingConfiguration (p. 1039) object

thingIndexingConfiguration (p. 348)

Thing indexing configuration.

Type: ThingIndexingConfiguration (p. 1042) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

349
 AWS IoT API Reference
GetIndexingConfiguration

• AWS SDK for Go

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

350
 AWS IoT API Reference
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. 351)

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

The job document content.

Type: String

Length Constraints: Maximum length of 32768.

Errors
InvalidRequestException

The request is not valid.

351
 AWS IoT API Reference
GetJobDocument

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

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

• AWS Command Line Interface

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

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

The logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

roleArn (p. 353)

The ARN of the IAM role that grants access.

Type: String

Errors
InternalException

An unexpected error has occurred.

353
 AWS IoT API Reference
GetLoggingOptions

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

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

• AWS Command Line Interface

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

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

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

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

356
 AWS IoT API Reference
GetOTAUpdate

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

otaUpdateInfo (p. 355)

The OTA update info.

Type: OTAUpdateInfo (p. 973) object

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

357
AWS IoT API Reference
GetOTAUpdate

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

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 359)

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

The percentile groups returned.

359
 AWS IoT API Reference
GetPercentiles

Type: Array of doubles

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

Required: No
queryString (p. 359)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 359)

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

The percentile values of the aggregated fields.

Type: Array of PercentPair (p. 979) objects

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

360
 AWS IoT API Reference
GetPercentiles

HTTP Status Code: 500

InvalidAggregationException

The aggregation is invalid.

HTTP Status Code: 400

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

361
 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. 362)

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

The date the policy was created.

Type: Timestamp

362
 AWS IoT API Reference
GetPolicy

defaultVersionId (p. 362)

The default policy version ID.

Type: String

Pattern: [0-9]+
generationId (p. 362)

The generation ID of the policy.

Type: String
lastModifiedDate (p. 362)

The date the policy was last modified.

Type: Timestamp
policyArn (p. 362)

The policy ARN.

Type: String
policyDocument (p. 362)

The JSON document that describes the policy.

Type: String

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

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

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

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

364
 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. 365)

The name of the policy.

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

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

Required: Yes
policyVersionId (p. 365)

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.

365
 AWS IoT API Reference
GetPolicyVersion

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

creationDate (p. 365)

The date the policy was created.

Type: Timestamp
generationId (p. 365)

The generation ID of the policy version.

Type: String
isDefaultVersion (p. 365)

Specifies whether the policy version is the default.

Type: Boolean
lastModifiedDate (p. 365)

The date the policy was last modified.

Type: Timestamp
policyArn (p. 365)

The policy ARN.

Type: String
policyDocument (p. 365)

The JSON document that describes the policy.

Type: String

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

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

The policy name.

Type: String

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

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

The policy version ID.

Type: String

Pattern: [0-9]+

Errors
InternalFailureException

An unexpected error has occurred.

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

367
 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. 368)

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.

368
 AWS IoT API Reference
GetRegistrationCode

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

369
 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. 370)

The aggregation field name.

Type: String

Length Constraints: Minimum length of 1.

Required: No
indexName (p. 370)

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

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

370
 AWS IoT API Reference
GetStatistics

queryVersion (p. 370)

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

The statistics returned by the Fleet Indexing service based on the query and aggregation field.

Type: Statistics (p. 1019) 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.

371
 AWS IoT API Reference
GetStatistics

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

372
 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. 373)

The name of the rule.

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

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

Required: Yes

Request Body
The request does not have a request body.

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

{
"rule": {
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {

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

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

375
 AWS IoT API Reference
GetTopicRule

]
},
"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": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",

376
 AWS IoT API Reference
GetTopicRule

"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": {
"batchMode": boolean,
"inputName": "string",
"messageId": "string",
"roleArn": "string"
},
"iotSiteWise": {
"putAssetPropertyValueEntries": [

377
 AWS IoT API Reference
GetTopicRule

{
"assetId": "string",
"entryId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": "string",
"timeInSeconds": "string"
},
"value": {
"booleanValue": "string",
"doubleValue": "string",
"integerValue": "string",
"stringValue": "string"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"
},
"destinationArn": "string",
"key": "string",
"partition": "string",
"topic": "string"
},
"kinesis": {
"partitionKey": "string",
"roleArn": "string",
"streamName": "string"
},
"lambda": {
"functionArn": "string"
},
"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",

378
 AWS IoT API Reference
GetTopicRule

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

379
 AWS IoT API Reference
GetTopicRule

rule (p. 373)

The rule.

Type: TopicRule (p. 1053) object

ruleArn (p. 373)

The rule ARN.

Type: String

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

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

380
 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. 381)

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

The topic rule destination.

381
 AWS IoT API Reference
GetTopicRuleDestination

Type: TopicRuleDestination (p. 1055) object

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

382
 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. 383)

The default log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

disableAllLogs (p. 383)

Disables all logs.

Type: Boolean
roleArn (p. 383)

The IAM role ARN AWS IoT uses to write to your CloudWatch logs.

Type: String

383
 AWS IoT API Reference
GetV2LoggingOptions

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

NotConfiguredException

The resource is not configured.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

384
 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. 385)

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

listSuppressedAlerts (p. 385)

A list of all suppressed alerts.

maxResults (p. 385)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 385)

The token for the next set of results.

securityProfileName (p. 385)

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. 385)

The name of the thing whose active violations are listed.

Length Constraints: Minimum length of 1. Maximum length of 128.

verificationState (p. 385)

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.

385
 AWS IoT API Reference
ListActiveViolations

Response Syntax
HTTP/1.1 200
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" ]
}
},
"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.

386
 AWS IoT API Reference
ListActiveViolations

The following data is returned in JSON format by the service.

activeViolations (p. 386)

The list of active violations.

Type: Array of ActiveViolation (p. 817) objects

nextToken (p. 386)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

387
 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. 388)

The token to retrieve the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 388)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

recursive (p. 388)

When true, recursively list attached policies.

target (p. 388)

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"
}
]

388
 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. 388)

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. 388)

The policies.

Type: Array of Policy (p. 980) 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.

389
 AWS IoT API Reference
ListAttachedPolicies

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

390
 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. 391)

A filter to limit results to the findings for the specified audit check.

Type: String

Required: No
endTime (p. 391)

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.

391
 AWS IoT API Reference
ListAuditFindings

Type: Timestamp

Required: No
listSuppressedFindings (p. 391)

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. 391)

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. 391)

The token for the next set of results.

Type: String

Required: No
resourceIdentifier (p. 391)

Information identifying the noncompliant resource.

Type: ResourceIdentifier (p. 997) object

Required: No
startTime (p. 391)

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. 391)

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

392
 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

393
 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. 392)

The findings (results) of the audit.

Type: Array of AuditFinding (p. 830) objects

nextToken (p. 392)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

394
 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. 395)

Specify this filter to limit results to those with a specific status.

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED | SKIPPED | PENDING

findingId (p. 395)

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. 395)

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. 395)

The token for the next set of results.

taskId (p. 395)

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

395
 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. 395)

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. 832) objects

nextToken (p. 395)

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:

396
 AWS IoT API Reference
ListAuditMitigationActionsExecutions

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

397
 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. 398)

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. 398)

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. 398)

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. 398)

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. 398)

The token for the next set of results.

startTime (p. 398)

Specify this filter to limit results to tasks that began on or after a specific date and time.

Required: Yes
taskStatus (p. 398)

Specify this filter to limit results to tasks that are in a specific state.

Valid Values: IN_PROGRESS | COMPLETED | FAILED | CANCELED

398
 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. 399)

The token for the next set of results.

Type: String
tasks (p. 399)

The collection of audit mitigation tasks that matched the filter criteria.

Type: Array of AuditMitigationActionsTaskMetadata (p. 834) 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:

399
 AWS IoT API Reference
ListAuditMitigationActionsTasks

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

400
 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. 401)

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. 401)

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.)

401
 AWS IoT API Reference
ListAuditSuppressions

Type: String

Required: No
maxResults (p. 401)

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. 401)

The token for the next set of results.

Type: String

Required: No
resourceIdentifier (p. 401)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 997) 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
}
]

402
 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. 402)

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. 402)

List of audit suppressions.

Type: Array of AuditSuppression (p. 837) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

403
 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. 404)

The end of the time period.

Required: Yes
maxResults (p. 404)

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. 404)

The token for the next set of results.

startTime (p. 404)

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. 404)

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. 404)

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

404
 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. 404)

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. 404)

The audits that were performed during the specified time period.

Type: Array of AuditTaskMetadata (p. 839) 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

405
 AWS IoT API Reference
ListAuditTasks

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

406
 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. 407)

Return the list of authorizers in ascending alphabetical order.

marker (p. 407)

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. 407)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

status (p. 407)

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"
}

407
 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. 407)

The authorizers.

Type: Array of AuthorizerSummary (p. 844) objects

nextMarker (p. 407)

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++

408
 AWS IoT API Reference
ListAuthorizers

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

409
 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. 410)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namePrefixFilter (p. 410)

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. 410)

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.

410
 AWS IoT API Reference
ListBillingGroups

The following data is returned in JSON format by the service.

billingGroups (p. 410)

The list of billing groups.

Type: Array of GroupNameAndArn (p. 908) objects

nextToken (p. 410)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

411
 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. 412)

Determines the order of the results.

marker (p. 412)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 412)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

templateName (p. 412)

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": [
{

412
 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. 412)

The CA certificates registered in your AWS account.

Type: Array of CACertificate (p. 864) objects

nextMarker (p. 412)

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

413
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

414
 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. 415)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
marker (p. 415)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 415)

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"
}

415
 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. 415)

The descriptions of the certificates.

Type: Array of Certificate (p. 868) objects

nextMarker (p. 415)

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++

416
 AWS IoT API Reference
ListCertificates

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

417
 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. 418)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
caCertificateId (p. 418)

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. 418)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 418)

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": [
{

418
 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. 418)

The device certificates signed by the specified CA certificate.

Type: Array of Certificate (p. 868) objects

nextMarker (p. 418)

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

419
 AWS IoT API Reference
ListCertificatesByCA

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

420
 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. 421)

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. 421)

The token for the next set of results.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"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. 421)

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. 421)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

421
 AWS IoT API Reference
ListCustomMetrics

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

422
 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. 423)

The end of the time period for which ML Detect mitigation actions executions are returned.
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)

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. 423)

The unique identifier of the task.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+
thingName (p. 423)

The name of the thing whose mitigation actions are listed.

Length Constraints: Minimum length of 1. Maximum length of 128.

violationId (p. 423)

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.

423
 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. 424)

List of actions executions.

Type: Array of DetectMitigationActionExecution (p. 885) objects

nextToken (p. 424)

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

424
 AWS IoT API Reference
ListDetectMitigationActionsExecutions

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

425
 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. 426)

The end of the time period for which ML Detect mitigation actions tasks are returned.

Required: Yes
maxResults (p. 426)

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. 426)

The token for the next set of results.

startTime (p. 426)

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" ]

426
 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. 426)

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. 426)

The collection of ML Detect mitigation tasks that matched the filter criteria.

Type: Array of DetectMitigationActionsTaskSummary (p. 888) objects

427
 AWS IoT API Reference
ListDetectMitigationActionsTasks

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

428
 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. 429)

The maximum number of results to retrieve at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 429)

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. 429)

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:_-]+

429
 AWS IoT API Reference
ListDimensions

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

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

430
 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. 431)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 431)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

serviceType (p. 431)

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.

431
 AWS IoT API Reference
ListDomainConfigurations

The following data is returned in JSON format by the service.

domainConfigurations (p. 431)

A list of objects that contain summary information about the user's domain configurations.

Type: Array of DomainConfigurationSummary (p. 893) objects

nextMarker (p. 431)

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

432
 AWS IoT API Reference
ListDomainConfigurations

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

433
 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. 434)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 434)

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. 434)

The list of fleet metrics objects.

Type: Array of FleetMetricNameAndArn (p. 907) objects

434
 AWS IoT API Reference
ListFleetMetrics

nextToken (p. 434)

The token for the next set of results. Will not be returned if the operation has returned all results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

435
 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. 436)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 500.

nextToken (p. 436)

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. 436)

The index names.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+
nextToken (p. 436)

The token used to get the next set of results, or null if there are no additional results.

436
 AWS IoT API Reference
ListIndices

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

437
 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. 438)

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. 438)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 438)

The token to retrieve the next set of results.

status (p. 438)

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,

438
 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. 438)

A list of job execution summaries.

Type: Array of JobExecutionSummaryForJob (p. 936) objects

nextToken (p. 438)

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++

439
 AWS IoT API Reference
ListJobExecutionsForJob

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

440
 AWS IoT API Reference
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. 441)

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. 441)

The maximum number of results to be returned per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namespaceId (p. 441)

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. 441)

The token to retrieve the next set of results.

status (p. 441)

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. 441)

The thing name.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

441
 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. 442)

A list of job execution summaries.

Type: Array of JobExecutionSummaryForThing (p. 937) objects

nextToken (p. 442)

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

442
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

443
 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. 444)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

namespaceId (p. 444)

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. 444)

The token to retrieve the next set of results.

status (p. 444)

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. 444)

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.

444
 AWS IoT API Reference
ListJobs

Valid Values: CONTINUOUS | SNAPSHOT

thingGroupId (p. 444)

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. 444)

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. 445)

A list of jobs.

Type: Array of JobSummary (p. 940) objects

nextToken (p. 445)

The token for the next set of results, or null if there are no additional results.

Type: String

445
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

446
 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. 447)

The maximum number of results to return in the list.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 447)

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. 447)

A list of objects that contain information about the job templates.

Type: Array of JobTemplateSummary (p. 942) objects

447
 AWS IoT API Reference
ListJobTemplates

nextToken (p. 447)

The token for the next set of results, or null if there are no additional results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

448
 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. 449)

Maximum number of entries that can be returned.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 449)

The token to retrieve the next set of results.

templateName (p. 449)

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.

449
 AWS IoT API Reference
ListManagedJobTemplates

The following data is returned in JSON format by the service.

managedJobTemplates (p. 449)

A list of managed job templates that are returned.

Type: Array of ManagedJobTemplateSummary (p. 955) objects

nextToken (p. 449)

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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

450
 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. 451)

The dimension name.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+
dimensionValueOperator (p. 451)

The dimension value operator.

Valid Values: IN | NOT_IN

endTime (p. 451)

The end of the time period for which metric values are returned.

Required: Yes
maxResults (p. 451)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

metricName (p. 451)

The name of the security profile metric for which values are returned.

Required: Yes
nextToken (p. 451)

The token for the next set of results.

startTime (p. 451)

The start of the time period for which metric values are returned.

Required: Yes
thingName (p. 451)

The name of the thing for which security profile metric values are returned.

Length Constraints: Minimum length of 1. Maximum length of 128.

451
 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. 452)

The data the thing reports for the metric during the specified time period.

Type: Array of MetricDatum (p. 957) objects

nextToken (p. 452)

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

452
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

453
 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. 454)

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. 454)

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. 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

{
"actionIdentifiers": [
{
"actionArn": "string",
"actionName": "string",
"creationDate": number
}
],
"nextToken": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

454
 AWS IoT API Reference
ListMitigationActions

The following data is returned in JSON format by the service.

actionIdentifiers (p. 454)

A set of actions that matched the specified filter criteria.

Type: Array of MitigationActionIdentifier (p. 963) objects

nextToken (p. 454)

The token for the next set of results.

Type: String

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

455
 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. 456)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 456)

A token used to retrieve the next set of results.

otaUpdateStatus (p. 456)

The OTA update job status.

Valid Values: CREATE_PENDING | CREATE_IN_PROGRESS | CREATE_COMPLETE |

CREATE_FAILED

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"otaUpdates": [
{
"creationDate": number,
"otaUpdateArn": "string",
"otaUpdateId": "string"
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

456
 AWS IoT API Reference
ListOTAUpdates

The following data is returned in JSON format by the service.

nextToken (p. 456)

A token to use to get the next set of results.

Type: String
otaUpdates (p. 456)

A list of OTA update jobs.

Type: Array of OTAUpdateSummary (p. 976) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

457
AWS IoT API Reference
ListOTAUpdates

458
 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. 459)

Specifies the order for results. If True, the results are returned in ascending order, based on the
creation date.
marker (p. 459)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 459)

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"
}
]
}

459
 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. 459)

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. 459)

The certificates that are being transferred but not yet accepted.

Type: Array of OutgoingCertificate (p. 977) 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++

460
 AWS IoT API Reference
ListOutgoingCertificates

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

461
 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. 462)

Specifies the order for results. If true, the results are returned in ascending creation order.
marker (p. 462)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 462)

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.

462
 AWS IoT API Reference
ListPolicies

nextMarker (p. 462)

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. 462)

The descriptions of the policies.

Type: Array of Policy (p. 980) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

463
 AWS IoT API Reference
ListPolicies

• AWS SDK for Ruby V3

464
 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. 499) 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. 465)

Specifies the order for results. If true, the results are returned in ascending creation order.
marker (p. 465)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 465)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

policyName (p. 465)

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

465
 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. 465)

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. 465)

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

466
 AWS IoT API Reference
ListPolicyPrincipals

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

467
 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. 468)

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. 468)

The policy versions.

Type: Array of PolicyVersion (p. 981) objects

468
 AWS IoT API Reference
ListPolicyVersions

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

469
 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. 388) 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. 470)

Specifies the order for results. If true, results are returned in ascending creation order.
marker (p. 470)

The marker for the next set of results.

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
pageSize (p. 470)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 250.

principal (p. 470)

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": [

470
 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. 470)

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. 470)

The policies.

Type: Array of Policy (p. 980) 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.

471
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

472
 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. 473)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 473)

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. 473)

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. 473)

The token to use to get the next set of results, or null if there are no additional results.

473
 AWS IoT API Reference
ListPrincipalThings

Type: String
things (p. 473)

The things.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

474
 AWS IoT API Reference
ListPrincipalThings

• AWS SDK for Python

• AWS SDK for Ruby V3

475
 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. 476)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 476)

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. 476)

A token to retrieve the next set of results.

476
 AWS IoT API Reference
ListProvisioningTemplates

Type: String
templates (p. 476)

A list of provisioning templates

Type: Array of ProvisioningTemplateSummary (p. 985) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

477
 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. 478)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 478)

A token to retrieve the next set of results.

templateName (p. 478)

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.

478
 AWS IoT API Reference
ListProvisioningTemplateVersions

The following data is returned in JSON format by the service.

nextToken (p. 478)

A token to retrieve the next set of results.

Type: String
versions (p. 478)

The list of provisioning template versions.

Type: Array of ProvisioningTemplateVersionSummary (p. 987) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

479
 AWS IoT API Reference
ListProvisioningTemplateVersions

480
 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. 481)

The finding Id.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+

Required: Yes
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 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.

481
 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. 482)

A token that can be used to retrieve the next set of results, or null for the first API call.

Type: String
relatedResources (p. 482)

The related resources.

Type: Array of RelatedResource (p. 994) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

482
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

483
 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. 484)

Return the list of role aliases in ascending alphabetical order.

marker (p. 484)

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. 484)

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. 484)

A marker used to get the next set of results.

484
 AWS IoT API Reference
ListRoleAliases

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [A-Za-z0-9+/]+={0,2}
roleAliases (p. 484)

The role aliases.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\w=,@-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

485
 AWS IoT API Reference
ListRoleAliases

• AWS SDK for Ruby V3

486
 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. 487)

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. 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",
"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. 487)

A token that can be used to retrieve the next set of results, or null if there are no additional results.

487
 AWS IoT API Reference
ListScheduledAudits

Type: String
scheduledAudits (p. 487)

The list of scheduled audits.

Type: Array of ScheduledAuditMetadata (p. 1006) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

488
 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. 489)

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. 489)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

metricName (p. 489)

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. 489)

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

489
 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. 489)

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. 489)

A list of security profile identifiers (names and ARNs).

Type: Array of SecurityProfileIdentifier (p. 1009) 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++

490
 AWS IoT API Reference
ListSecurityProfiles

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

491
 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. 492)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 492)

The token for the next set of results.

recursive (p. 492)

If true, return child groups too.

securityProfileTargetArn (p. 492)

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"
}
}
]

492
 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. 492)

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. 492)

A list of security profiles and their associated targets.

Type: Array of SecurityProfileTargetMapping (p. 1011) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

493
 AWS IoT API Reference
ListSecurityProfilesForTarget

• AWS SDK for Ruby V3

494
 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. 495)

Set to true to return the list of streams in ascending order.

maxResults (p. 495)

The maximum number of results to return at a time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 495)

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.

495
 AWS IoT API Reference
ListStreams

nextToken (p. 495)

A token used to get the next set of results.

Type: String
streams (p. 495)

A list of streams.

Type: Array of StreamSummary (p. 1026) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

496
 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. 497)

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. 497)

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. 497)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

497
 AWS IoT API Reference
ListTagsForResource

tags (p. 497)

The list of tags assigned to the resource.

Type: Array of Tag (p. 1027) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

498
 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. 499)

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. 499)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

policyName (p. 499)

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.

499
 AWS IoT API Reference
ListTargetsForPolicy

The following data is returned in JSON format by the service.

nextMarker (p. 499)

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. 499)

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:

500
 AWS IoT API Reference
ListTargetsForPolicy

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

501
 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. 502)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 502)

The token for the next set of results.

securityProfileName (p. 502)

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.

502
 AWS IoT API Reference
ListTargetsForSecurityProfile

The following data is returned in JSON format by the service.

nextToken (p. 502)

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. 502)

The thing groups to which the security profile is attached.

Type: Array of SecurityProfileTarget (p. 1010) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

503
 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. 504)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

namePrefixFilter (p. 504)

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. 504)

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. 504)

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. 504)

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",

504
 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. 504)

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. 504)

The thing groups.

Type: Array of GroupNameAndArn (p. 908) 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++

505
 AWS IoT API Reference
ListThingGroups

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

506
 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. 507)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 507)

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. 507)

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.

507
 AWS IoT API Reference
ListThingGroupsForThing

The following data is returned in JSON format by the service.

nextToken (p. 507)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
thingGroups (p. 507)

The thing groups.

Type: Array of GroupNameAndArn (p. 908) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

508
 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. 509)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 509)

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. 509)

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.

509
 AWS IoT API Reference
ListThingPrincipals

nextToken (p. 509)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
principals (p. 509)

The principals associated with the thing.

Type: Array of strings

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

510
 AWS IoT API Reference
ListThingPrincipals

• AWS SDK for Python

• AWS SDK for Ruby V3

511
 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. 512)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 512)

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. 512)

The type of task report.

Valid Values: ERRORS | RESULTS

Required: Yes
taskId (p. 512)

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.

512
 AWS IoT API Reference
ListThingRegistrationTaskReports

The following data is returned in JSON format by the service.

nextToken (p. 512)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
reportType (p. 512)

The type of task report.

Type: String

Valid Values: ERRORS | RESULTS

resourceLinks (p. 512)

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

513
 AWS IoT API Reference
ListThingRegistrationTaskReports

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

514
 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. 515)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 515)

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to
receive the first set of results.
status (p. 515)

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. 515)

The token to use to get the next set of results, or null if there are no additional results.

515
 AWS IoT API Reference
ListThingRegistrationTasks

Type: String
taskIds (p. 515)

A list of bulk thing provisioning task IDs.

Type: Array of strings

Length Constraints: Maximum length of 40.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

516
 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. 517)

The attribute name used to search for things.

Length Constraints: Maximum length of 128.

Pattern: [a-zA-Z0-9_.,@/:#-]+
attributeValue (p. 517)

The attribute value used to search for things.

Length Constraints: Maximum length of 800.

Pattern: [a-zA-Z0-9_.,@/:#-]*
maxResults (p. 517)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 517)

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. 517)

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:_-]+

517
 AWS IoT API Reference
ListThings

usePrefixAttributeValue (p. 517)

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. 518)

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. 518)

The things.

Type: Array of ThingAttribute (p. 1032) objects

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

518
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

519
 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. 520)

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. 520)

The maximum number of results to return per request.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 520)

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.

520
 AWS IoT API Reference
ListThingsInBillingGroup

nextToken (p. 520)

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. 520)

A list of things in the billing group.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

521
 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. 522)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 522)

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. 522)

When true, list things in this thing group and in all child groups as well.
thingGroupName (p. 522)

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.

522
 AWS IoT API Reference
ListThingsInThingGroup

The following data is returned in JSON format by the service.

nextToken (p. 522)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
things (p. 522)

The things in the specified thing group.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

523
 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. 524)

The maximum number of results to return in this operation.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 524)

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. 524)

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"

524
 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. 524)

The token for the next set of results. Will not be returned if operation has returned all results.

Type: String
thingTypes (p. 524)

The thing types.

Type: Array of ThingTypeDefinition (p. 1044) 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

525
 AWS IoT API Reference
ListThingTypes

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

526
 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. 527)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 1000.

nextToken (p. 527)

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"
}

527
 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. 527)

Information about a topic rule destination.

Type: Array of TopicRuleDestinationSummary (p. 1058) objects

nextToken (p. 527)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

528
 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. 529)

The maximum number of results to return.

Valid Range: Minimum value of 1. Maximum value of 10000.

nextToken (p. 529)

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. 529)

Specifies whether the rule is disabled.

topic (p. 529)

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"
}
]
}

529
 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. 529)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
rules (p. 529)

The rules.

Type: Array of TopicRuleListItem (p. 1060) objects

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

530
 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. 531)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 531)

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. 531)

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

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.

531
 AWS IoT API Reference
ListV2LoggingLevels

The following data is returned in JSON format by the service.

logTargetConfigurations (p. 531)

The logging configuration for a target.

Type: Array of LogTargetConfiguration (p. 953) objects

nextToken (p. 531)

The token to use to get the next set of results, or null if there are no additional results.

Type: String

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

NotConfiguredException

The resource is not configured.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

532
 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. 533)

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

endTime (p. 533)

The end time for the alerts to be listed.

Required: Yes
listSuppressedAlerts (p. 533)

A list of all suppressed alerts.

maxResults (p. 533)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken (p. 533)

The token for the next set of results.

securityProfileName (p. 533)

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. 533)

The start time for the alerts to be listed.

Required: Yes
thingName (p. 533)

A filter to limit results to those alerts caused by the specified thing.

533
 AWS IoT API Reference
ListViolationEvents

Length Constraints: Minimum length of 1. Maximum length of 128.

verificationState (p. 533)

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" ]
}
},
"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",
"violationEventAdditionalInfo": {

534
 AWS IoT API Reference
ListViolationEvents

"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. 534)

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. 534)

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. 1069) 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

535
 AWS IoT API Reference
ListViolationEvents

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

536
 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. 537)

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. 537)

The verification state of the violation.

Type: String

Valid Values: FALSE_POSITIVE | BENIGN_POSITIVE | TRUE_POSITIVE | UNKNOWN

Required: Yes
verificationStateDescription (p. 537)

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

537
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

538
 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. 539)

Allows this CA certificate to be used for auto registration of device certificates.

setAsActive (p. 539)

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. 539)

The CA certificate.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 65536.

Pattern: [\s\S]*

539
 AWS IoT API Reference
RegisterCACertificate

Required: Yes
certificateMode (p. 539)

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. 539)

Information about the registration configuration.

Type: RegistrationConfig (p. 993) object

Required: No
tags (p. 539)

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. 1027) objects

Required: No
verificationCertificate (p. 539)

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"
}

540
 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. 540)

The CA certificate ARN.

Type: String
certificateId (p. 540)

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

541
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

542
 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. 543)

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. 543)

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. 543)

The certificate data, in PEM format.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 65536.

Pattern: [\s\S]*

Required: Yes

543
 AWS IoT API Reference
RegisterCertificate

status (p. 543)

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. 544)

The certificate ARN.

Type: String
certificateId (p. 544)

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

544
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

545
 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. 546)

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. 546)

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"
}

546
 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. 546)

The Amazon Resource Name (ARN) of the registered certificate.

Type: String
certificateId (p. 546)

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

547
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

548
 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. 549)

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. 549)

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

549
 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. 550)

The certificate data, in PEM format.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 65536.

Pattern: [\s\S]*
resourceArns (p. 550)

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

550
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

551
 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. 415) 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. 552)

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. 552)

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

552
 AWS IoT API Reference
RejectCertificateTransfer

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

TransferAlreadyCompletedException

You can't revert the certificate transfer because the transfer is already complete.

HTTP Status Code: 410

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

553
 AWS IoT API Reference
RejectCertificateTransfer

• AWS SDK for Ruby V3

554
 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. 555)

The ARN of the billing group.

Type: String

Required: No
billingGroupName (p. 555)

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. 555)

The ARN of the thing to be removed from the billing group.

Type: String

Required: No
thingName (p. 555)

The name of the thing to be removed from the billing group.

555
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

556
 AWS IoT API Reference
RemoveThingFromBillingGroup

557
 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. 558)

The ARN of the thing to remove from the group.

Type: String

Required: No
thingGroupArn (p. 558)

The group ARN.

Type: String

Required: No
thingGroupName (p. 558)

The group name.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: No
thingName (p. 558)

The name of the thing to remove from the group.

558
 AWS IoT API Reference
RemoveThingFromThingGroup

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: No

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

559
 AWS IoT API Reference
RemoveThingFromThingGroup

560
 AWS IoT API Reference
ReplaceTopicRule

ReplaceTopicRule
Service: AWS IoT

Replaces the rule. You must specify all parameters for the new rule. Creating rules is an administrator-
level action. Any user who has permission to create rules will be able to access data processed by the
rule.

Requires permission to access the ReplaceTopicRule action.

Request Syntax
PATCH /rules/ruleName HTTP/1.1
Content-type: application/json

{
"topicRulePayload": {
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "string",
"roleArn": "string",
"stateReason": "string",
"stateValue": "string"
},
"cloudwatchLogs": {
"logGroupName": "string",
"roleArn": "string"
},
"cloudwatchMetric": {
"metricName": "string",
"metricNamespace": "string",
"metricTimestamp": "string",
"metricUnit": "string",
"metricValue": "string",
"roleArn": "string"
},
"dynamoDB": {
"hashKeyField": "string",
"hashKeyType": "string",
"hashKeyValue": "string",
"operation": "string",
"payloadField": "string",
"rangeKeyField": "string",
"rangeKeyType": "string",
"rangeKeyValue": "string",
"roleArn": "string",
"tableName": "string"
},
"dynamoDBv2": {
"putItem": {
"tableName": "string"
},
"roleArn": "string"
},
"elasticsearch": {
"endpoint": "string",
"id": "string",
"index": "string",
"roleArn": "string",
"type": "string"
},
"firehose": {
"batchMode": boolean,

561
 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",
"key": "string",
"partition": "string",

562
 AWS IoT API Reference
ReplaceTopicRule

"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"
},
"sqs": {
"queueUrl": "string",
"roleArn": "string",
"useBase64": boolean
},

563
 AWS IoT API Reference
ReplaceTopicRule

"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": {
"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",

564
 AWS IoT API Reference
ReplaceTopicRule

"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"
}
}
]
}
],
"roleArn": "string"
},
"kafka": {
"clientProperties": {
"string" : "string"

565
 AWS IoT API Reference
ReplaceTopicRule

},
"destinationArn": "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"
},
"sqs": {

566
 AWS IoT API Reference
ReplaceTopicRule

"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. 561)

The name of the rule.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: ^[a-zA-Z0-9_]+$

Required: Yes

Request Body
The request accepts the following data in JSON format.

topicRulePayload (p. 561)

The rule payload.

Type: TopicRulePayload (p. 1061) object

Required: Yes

Response Syntax
HTTP/1.1 200

567
 AWS IoT API Reference
ReplaceTopicRule

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
ConflictingResourceUpdateException

A conflicting resource update exception. This exception is thrown when two pending updates cause a
conflict.

HTTP Status Code: 409

InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

SqlParseException

The Rule-SQL expression can't be parsed correctly.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

568
 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. 569)

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. 569)

The maximum number of results to return at one time.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 500.

Required: No
nextToken (p. 569)

The token used to get the next set of results, or null if there are no additional results.

Type: String

Required: No
queryString (p. 569)

The search query string. For more information about the search query syntax, see Query syntax.

569
 AWS IoT API Reference
SearchIndex

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
queryVersion (p. 569)

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.

nextToken (p. 570)

The token used to get the next set of results, or null if there are no additional results.

570
 AWS IoT API Reference
SearchIndex

Type: String
thingGroups (p. 570)

The thing groups that match the search query.

Type: Array of ThingGroupDocument (p. 1037) objects

things (p. 570)

The things that match the search query.

Type: Array of ThingDocument (p. 1035) objects

Errors
IndexNotReadyException

The index is not ready.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

571
 AWS IoT API Reference
SearchIndex

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

572
 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. 573)

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. 573)

The authorizer ARN.

573
 AWS IoT API Reference
SetDefaultAuthorizer

Type: String

Length Constraints: Maximum length of 2048.

authorizerName (p. 573)

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

574
 AWS IoT API Reference
SetDefaultAuthorizer

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

575
 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. 470) 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. 576)

The policy name.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\w+=,.@-]+

Required: Yes
policyVersionId (p. 576)

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

576
 AWS IoT API Reference
SetDefaultPolicyVersion

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

577
 AWS IoT API Reference
SetLoggingOptions

SetLoggingOptions
Service: AWS IoT

Sets the logging options.

NOTE: use of this command is not recommended. Use SetV2LoggingOptions instead.

Requires permission to access the SetLoggingOptions action.

Request Syntax
POST /loggingOptions HTTP/1.1
Content-type: application/json

{
"loggingOptionsPayload": {
"logLevel": "string",
"roleArn": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

loggingOptionsPayload (p. 578)

The logging options payload.

Type: LoggingOptionsPayload (p. 951) object

Required: Yes

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

578
 AWS IoT API Reference
SetLoggingOptions

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

579
 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. 580)

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: Yes
logTarget (p. 580)

The log target.

Type: LogTarget (p. 952) 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.

580
 AWS IoT API Reference
SetV2LoggingLevel

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

NotConfiguredException

The resource is not configured.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

581
 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. 582)

The default logging level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
disableAllLogs (p. 582)

If true all logs are disabled. The default is false.

Type: Boolean

Required: No
roleArn (p. 582)

The ARN of the role that allows IoT to write to Cloudwatch logs.

Type: String

Required: No

Response Syntax
HTTP/1.1 200

582
 AWS IoT API Reference
SetV2LoggingOptions

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

583
 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. 584)

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. 584)

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_-]+

584
 AWS IoT API Reference
StartAuditMitigationActionsTask

Required: Yes
clientRequestToken (p. 584)

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. 584)

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. 835) 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. 585)

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

585
 AWS IoT API Reference
StartAuditMitigationActionsTask

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

TaskAlreadyExistsException

This exception occurs if you attempt to start a task with the same task-id as an existing task but with
a different clientRequestToken.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

586
 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. 587)

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. 587)

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

587
 AWS IoT API Reference
StartDetectMitigationActionsTask

clientRequestToken (p. 587)

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. 587)

Specifies to list only active violations.

Type: Boolean

Required: No
includeSuppressedAlerts (p. 587)

Specifies to include suppressed alerts.

Type: Boolean

Required: No
target (p. 587)

Specifies the ML Detect findings to which the mitigation actions are applied.

Type: DetectMitigationActionsTaskTarget (p. 890) object

Required: Yes
violationEventOccurrenceRange (p. 587)

Specifies the time period of which violation events occurred between.

Type: ViolationEventOccurrenceRange (p. 1072) 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.

588
 AWS IoT API Reference
StartDetectMitigationActionsTask

taskId (p. 588)

The unique identifier of the task.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

TaskAlreadyExistsException

This exception occurs if you attempt to start a task with the same task-id as an existing task but with
a different clientRequestToken.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

589
 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. 590)

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. 590)

The ID of the on-demand audit you started.

Type: String

590
 AWS IoT API Reference
StartOnDemandAuditTask

Length Constraints: Minimum length of 1. Maximum length of 40.

Pattern: [a-zA-Z0-9\-]+

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

591
 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. 592)

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. 592)

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. 592)

The IAM role ARN that grants permission the input file.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

592
 AWS IoT API Reference
StartThingRegistrationTask

Required: Yes
templateBody (p. 592)

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. 593)

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.

593
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

594
 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. 595)

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

595
 AWS IoT API Reference
StopThingRegistrationTask

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

596
 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. 597)

The ARN of the resource.

Type: String

Required: Yes
tags (p. 597)

The new or modified tags for the resource.

Type: Array of Tag (p. 1027) 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.

597
 AWS IoT API Reference
TagResource

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

598
 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. 599)

The MQTT client ID.

Request Body
The request accepts the following data in JSON format.

authInfos (p. 599)

A list of authorization info objects. Simulating authorization will create a response for each
authInfo object in the list.

Type: Array of AuthInfo (p. 840) objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: Yes
cognitoIdentityPoolId (p. 599)

The Cognito identity pool ID.

Type: String

Required: No
policyNamesToAdd (p. 599)

When testing custom authorization, the policies specified here are treated as if they are attached to
the principal being authorized.

599
 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. 599)

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. 599)

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": [
{

600
 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. 600)

The authentication results.

Type: Array of AuthResult (p. 845) 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.

601
 AWS IoT API Reference
TestAuthorization

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

602
 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. 603)

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. 603)

Specifies a test HTTP authorization request.

Type: HttpContext (p. 913) object

Required: No

603
 AWS IoT API Reference
TestInvokeAuthorizer

mqttContext (p. 603)

Specifies a test MQTT authorization request.

Type: MqttContext (p. 966) object

Required: No
tlsContext (p. 603)

Specifies a test TLS authorization request.

Type: TlsContext (p. 1052) object

Required: No
token (p. 603)

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. 603)

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. 604)

The number of seconds after which the connection is terminated.

604
 AWS IoT API Reference
TestInvokeAuthorizer

Type: Integer
isAuthenticated (p. 604)

True if the token is authenticated, otherwise false.

Type: Boolean
policyDocuments (p. 604)

IAM policy documents.

Type: Array of strings

Length Constraints: Minimum length of 0. Maximum length of 404600.

Pattern: [\s\S]*
principalId (p. 604)

The principal ID.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9]+
refreshAfterInSeconds (p. 604)

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

605
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

606
 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. 628) action to deactivate it.

The certificate must not have any policies attached to it. You can use the DetachPolicy (p. 324) 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. 607)

The ID of the certificate. (The last part of the certificate ARN contains the certificate ID.)

Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+

Required: Yes
targetAwsAccount (p. 607)

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. 607)

The transfer message.

607
 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. 608)

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

608
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

609
 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. 610)

The ARN of the resource.

Type: String

Required: Yes
tagKeys (p. 610)

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.

610
 AWS IoT API Reference
UntagResource

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

611
 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. 612)

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. 827) object map

Required: No
auditNotificationTargetConfigurations (p. 612)

Information about the targets to which audit notifications are sent.

612
 AWS IoT API Reference
UpdateAccountAuditConfiguration

Type: String to AuditNotificationTarget (p. 836) object map

Valid Keys: SNS

Required: No
roleArn (p. 612)

The Amazon Resource Name (ARN) of the role that grants permission to AWS IoT to access
information about your devices, policies, certificates, and other items as required when performing
an audit.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

613
 AWS IoT API Reference
UpdateAccountAuditConfiguration

• AWS SDK for Python

• AWS SDK for Ruby V3

614
 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. 615)

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. 615)

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

615
 AWS IoT API Reference
UpdateAuditSuppression

Pattern: [\p{Graph}\x20]*

Required: No
expirationDate (p. 615)

The expiration date (epoch timestamp in seconds) that you want the suppression to adhere to.

Type: Timestamp

Required: No
resourceIdentifier (p. 615)

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 997) object

Required: Yes
suppressIndefinitely (p. 615)

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

616
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

617
 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. 618)

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. 618)

The ARN of the authorizer's Lambda function.

Type: String

Length Constraints: Maximum length of 2048.

Pattern: [\s\S]*

Required: No
enableCachingForHttp (p. 618)

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

618
 AWS IoT API Reference
UpdateAuthorizer

Required: No
status (p. 618)

The status of the update authorizer request.

Type: String

Valid Values: ACTIVE | INACTIVE

Required: No
tokenKeyName (p. 618)

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. 618)

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. 619)

The authorizer ARN.

Type: String

619
 AWS IoT API Reference
UpdateAuthorizer

Length Constraints: Maximum length of 2048.

authorizerName (p. 619)

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++

620
 AWS IoT API Reference
UpdateAuthorizer

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

621
 AWS IoT API Reference
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. 622)

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. 622)

The properties of the billing group.

Type: BillingGroupProperties (p. 861) object

Required: Yes
expectedVersion (p. 622)

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

622
 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. 622)

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

623
 AWS IoT API Reference
UpdateBillingGroup

• AWS SDK for Java V2

• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

624
 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. 625)

The CA certificate identifier.

Length Constraints: Fixed length of 64.

Pattern: (0x)?[a-fA-F0-9]+

Required: Yes
newAutoRegistrationStatus (p. 625)

The new value for the auto registration status. Valid values are: "ENABLE" or "DISABLE".

Valid Values: ENABLE | DISABLE

newStatus (p. 625)

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. 625)

Information about the registration configuration.

Type: RegistrationConfig (p. 993) object

625
 AWS IoT API Reference
UpdateCACertificate

Required: No
removeAutoRegistration (p. 625)

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

626
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

627
 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. 628)

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. 628)

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

628
 AWS IoT API Reference
UpdateCertificate

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
CertificateStateException

The certificate operation is not allowed.

HTTP Status Code: 406

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

629
 AWS IoT API Reference
UpdateCertificate

• AWS SDK for Ruby V3

630
 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. 631)

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. 631)

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",

631
 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. 631)

The creation date of the custom metric in milliseconds since epoch.

Type: Timestamp
displayName (p. 631)

A friendly name in the console for the custom metric

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Graph}\x20]*
lastModifiedDate (p. 631)

The time the custom metric was last modified in milliseconds since epoch.

Type: Timestamp
metricArn (p. 631)

The Amazon Resource Number (ARN) of the custom metric.

Type: String
metricName (p. 631)

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. 631)

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.

632
 AWS IoT API Reference
UpdateCustomMetric

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

633
 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. 634)

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. 634)

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,

634
 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. 634)

The Amazon Resource Name (ARN)of the created dimension.

Type: String
creationDate (p. 634)

The date and time, in milliseconds since epoch, when the dimension was initially created.

Type: Timestamp
lastModifiedDate (p. 634)

The date and time, in milliseconds since epoch, when the dimension was most recently updated.

Type: Timestamp
name (p. 634)

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. 634)

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. 634)

The type of the dimension.

Type: String

Valid Values: TOPIC_FILTER

Errors
InternalFailureException

An unexpected error has occurred.

635
 AWS IoT API Reference
UpdateDimension

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

636
 AWS IoT API Reference
UpdateDomainConfiguration

UpdateDomainConfiguration
Service: AWS IoT

Updates values stored in the domain configuration. Domain configurations for default endpoints can't be
updated.

Requires permission to access the UpdateDomainConfiguration action.

Request Syntax
PUT /domainConfigurations/domainConfigurationName HTTP/1.1
Content-type: application/json

{
"authorizerConfig": {
"allowAuthorizerOverride": boolean,
"defaultAuthorizerName": "string"
},
"domainConfigurationStatus": "string",
"removeAuthorizerConfig": boolean
}

URI Request Parameters

The request uses the following URI parameters.

domainConfigurationName (p. 637)

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. 637)

An object that specifies the authorization service for a domain.

Type: AuthorizerConfig (p. 841) object

Required: No
domainConfigurationStatus (p. 637)

The status to which the domain configuration should be updated.

Type: String

Valid Values: ENABLED | DISABLED

Required: No

637
 AWS IoT API Reference
UpdateDomainConfiguration

removeAuthorizerConfig (p. 637)

Removes the authorization configuration from a domain.

Type: Boolean

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"domainConfigurationArn": "string",
"domainConfigurationName": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

domainConfigurationArn (p. 638)

The ARN of the domain configuration that was updated.

Type: String
domainConfigurationName (p. 638)

The name of the domain configuration that was updated.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\w.:-]+

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

638
 AWS IoT API Reference
UpdateDomainConfiguration

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

639
 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. 640)

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. 640)

The expected version of the dynamic thing group to update.

Type: Long

Required: No
indexName (p. 640)

The dynamic thing group index to update.

640
 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. 640)

The dynamic thing group search query string to update.

Type: String

Length Constraints: Minimum length of 1.

Required: No
queryVersion (p. 640)

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. 640)

The dynamic thing group properties to update.

Type: ThingGroupProperties (p. 1041) 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. 641)

The dynamic thing group version.

Type: Long

641
 AWS IoT API Reference
UpdateDynamicThingGroup

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidQueryException

The query is invalid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

An exception thrown when the version of an entity specified with the expectedVersion parameter
does not match the latest version in the system.

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

642
 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. 643)

The new event configuration values.

Type: String to Configuration (p. 881) 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

643
 AWS IoT API Reference
UpdateEventConfigurations

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

644
 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. 645)

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. 645)

The field to aggregate.

Type: String

Length Constraints: Minimum length of 1.

Required: No
aggregationType (p. 645)

The type of the aggregation query.

Type: AggregationType (p. 820) object

645
 AWS IoT API Reference
UpdateFleetMetric

Required: No
description (p. 645)

The description of the fleet metric.

Type: String

Length Constraints: Maximum length of 1024.

Pattern: [\p{Graph}\x20]*

Required: No
expectedVersion (p. 645)

The expected version of the fleet metric record in the registry.

Type: Long

Required: No
indexName (p. 645)

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. 645)

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. 645)

The search query string.

Type: String

Length Constraints: Minimum length of 1.

Required: No
queryVersion (p. 645)

The version of the query.

Type: String

Required: No
unit (p. 645)

Used to support unit transformation such as milliseconds to seconds. The unit must be supported by
CW metric.

646
 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

647
 AWS IoT API Reference
UpdateFleetMetric

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

An exception thrown when the version of an entity specified with the expectedVersion parameter
does not match the latest version in the system.

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

648
 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": {
"namedShadowNames": [ "string" ]
},
"managedFields": [
{
"name": "string",
"type": "string"
}
],
"namedShadowIndexingMode": "string",
"thingConnectivityIndexingMode": "string",
"thingIndexingMode": "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

649
 AWS IoT API Reference
UpdateIndexingConfiguration

thingGroupIndexingConfiguration (p. 649)

Thing group indexing configuration.

Type: ThingGroupIndexingConfiguration (p. 1039) object

Required: No
thingIndexingConfiguration (p. 649)

Thing indexing configuration.

Type: ThingIndexingConfiguration (p. 1042) object

Required: No

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

650
 AWS IoT API Reference
UpdateIndexingConfiguration

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

651
 AWS IoT API Reference
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. 652)

The ID of the job to be updated.

Length Constraints: Minimum length of 1. Maximum length of 64.

652
 AWS IoT API Reference
UpdateJob

Pattern: [a-zA-Z0-9_-]+

Required: Yes
namespaceId (p. 652)

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. 652)

Allows you to create criteria to abort a job.

Type: AbortConfig (p. 810) object

Required: No
description (p. 652)

A short text description of the job.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
jobExecutionsRetryConfig (p. 652)

Allows you to create the criteria to retry a job.

Type: JobExecutionsRetryConfig (p. 931) object

Required: No
jobExecutionsRolloutConfig (p. 652)

Allows you to create a staged rollout of the job.

Type: JobExecutionsRolloutConfig (p. 932) object

Required: No
presignedUrlConfig (p. 652)

Configuration information for pre-signed S3 URLs.

Type: PresignedUrlConfig (p. 983) object

Required: No

653
 AWS IoT API Reference
UpdateJob

timeoutConfig (p. 652)

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. 1047) 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
• AWS SDK for PHP V3
• AWS SDK for Python

654
 AWS IoT API Reference
UpdateJob

• AWS SDK for Ruby V3

655
 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. 656)

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.

656
 AWS IoT API Reference
UpdateMitigationAction

actionParams (p. 656)

Defines the type of action and the parameters for that action.

Type: MitigationActionParams (p. 964) object

Required: No
roleArn (p. 656)

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. 657)

The ARN for the new mitigation action.

Type: String
actionId (p. 657)

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

657
 AWS IoT API Reference
UpdateMitigationAction

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

658
 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. 659)

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. 659)

The ID of the default provisioning template version.

Type: Integer

Required: No
description (p. 659)

The description of the provisioning template.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 500.

Pattern: [^\p{C}]*

659
 AWS IoT API Reference
UpdateProvisioningTemplate

Required: No
enabled (p. 659)

True to enable the provisioning template, otherwise false.

Type: Boolean

Required: No
preProvisioningHook (p. 659)

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. 984) object

Required: No
provisioningRoleArn (p. 659)

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. 659)

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

660
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

661
 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. 662)

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. 662)

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. 662)

The role ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

662
 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. 663)

The role alias.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\w=,@-]+
roleAliasArn (p. 663)

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.

663
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

664
 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. 665)

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. 665)

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. 665)

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

665
 AWS IoT API Reference
UpdateScheduledAudit

Required: No
frequency (p. 665)

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. 665)

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. 666)

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.

666
 AWS IoT API Reference
UpdateScheduledAudit

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

667
 AWS IoT API Reference
UpdateSecurityProfile

UpdateSecurityProfile
Service: AWS IoT

Updates a Device Defender security profile.

Requires permission to access the UpdateSecurityProfile action.

Request Syntax
PATCH /security-profiles/securityProfileName?expectedVersion=expectedVersion HTTP/1.1
Content-type: application/json

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"deleteAdditionalMetricsToRetain": boolean,
"deleteAlertTargets": boolean,
"deleteBehaviors": boolean,

668
 AWS IoT API Reference
UpdateSecurityProfile

"securityProfileDescription": "string"
}

URI Request Parameters

The request uses the following URI parameters.

expectedVersion (p. 668)

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. 668)

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. 668)

This parameter has been deprecated.

Please use UpdateSecurityProfile:additionalMetricsToRetainV2 (p. 669) 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. 668)

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. 959) objects

Required: No
alertTargets (p. 668)

Where the alerts are sent. (Alerts are always sent to the console.)

Type: String to AlertTarget (p. 821) object map

Valid Keys: SNS

Required: No

669
 AWS IoT API Reference
UpdateSecurityProfile

behaviors (p. 668)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 854) objects

Array Members: Maximum number of 100 items.

Required: No
deleteAdditionalMetricsToRetain (p. 668)

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. 668)

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. 668)

If true, delete all behaviors defined for this security profile. If any behaviors are defined in the
current invocation, an exception occurs.

Type: Boolean

Required: No
securityProfileDescription (p. 668)

A description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"additionalMetricsToRetain": [ "string" ],
"additionalMetricsToRetainV2": [
{
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"

670
 AWS IoT API Reference
UpdateSecurityProfile

}
}
],
"alertTargets": {
"string" : {
"alertTargetArn": "string",
"roleArn": "string"
}
},
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
],
"creationDate": number,
"lastModifiedDate": number,
"securityProfileArn": "string",
"securityProfileDescription": "string",
"securityProfileName": "string",
"version": number
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

additionalMetricsToRetain (p. 670)

This parameter has been deprecated.

Please use UpdateSecurityProfile:additionalMetricsToRetainV2 (p. 672) 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

671
 AWS IoT API Reference
UpdateSecurityProfile

additionalMetricsToRetainV2 (p. 670)

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. 959) objects

alertTargets (p. 670)

Where the alerts are sent. (Alerts are always sent to the console.)

Type: String to AlertTarget (p. 821) object map

Valid Keys: SNS

behaviors (p. 670)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 854) objects

Array Members: Maximum number of 100 items.

creationDate (p. 670)

The time the security profile was created.

Type: Timestamp
lastModifiedDate (p. 670)

The time the security profile was last modified.

Type: Timestamp
securityProfileArn (p. 670)

The ARN of the security profile that was updated.

Type: String
securityProfileDescription (p. 670)

The description of the security profile.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*
securityProfileName (p. 670)

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. 670)

The updated version of the security profile.

Type: Long

672
 AWS IoT API Reference
UpdateSecurityProfile

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

VersionConflictException

An exception thrown when the version of an entity specified with the expectedVersion parameter
does not match the latest version in the system.

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

673
 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. 674)

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. 674)

The description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+

Required: No
files (p. 674)

The files associated with the stream.

674
 AWS IoT API Reference
UpdateStream

Type: Array of StreamFile (p. 1023) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: No
roleArn (p. 674)

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. 675)

A description of the stream.

Type: String

Length Constraints: Maximum length of 2028.

Pattern: [^\p{C}]+
streamArn (p. 675)

The stream ARN.

Type: String
streamId (p. 675)

The stream ID.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9_-]+
streamVersion (p. 675)

The stream version.

675
 AWS IoT API Reference
UpdateStream

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 65535.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

676
 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. 677)

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. 677)

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. 826) object

Required: No

677
 AWS IoT API Reference
UpdateThing

expectedVersion (p. 677)

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. 677)

Remove a thing type association. If true, the association is removed.

Type: Boolean

Required: No
thingTypeName (p. 677)

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.

678
 AWS IoT API Reference
UpdateThing

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

VersionConflictException

An exception thrown when the version of an entity specified with the expectedVersion parameter
does not match the latest version in the system.

HTTP Status Code: 409

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

679
 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. 680)

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. 680)

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. 680)

The thing group properties.

Type: ThingGroupProperties (p. 1041) object

Required: Yes

680
 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. 681)

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

681
 AWS IoT API Reference
UpdateThingGroup

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

682
 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. 683)

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. 683)

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. 683)

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

683
 AWS IoT API Reference
UpdateThingGroupsForThing

thingName (p. 683)

The thing whose group memberships will be updated.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: No

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3

684
 AWS IoT API Reference
UpdateThingGroupsForThing

• AWS SDK for Python

• AWS SDK for Ruby V3

685
 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. 686)

The ARN of the topic rule destination.

Type: String

Required: Yes
status (p. 686)

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.

686
 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

687
 AWS IoT API Reference
UpdateTopicRuleDestination

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V3

688
 AWS IoT API Reference
ValidateSecurityProfileBehaviors

ValidateSecurityProfileBehaviors
Service: AWS IoT

Validates a Device Defender security profile behaviors specification.

Requires permission to access the ValidateSecurityProfileBehaviors action.

Request Syntax
POST /security-profile-behaviors/validate HTTP/1.1
Content-type: application/json

{
"behaviors": [
{
"criteria": {
"comparisonOperator": "string",
"consecutiveDatapointsToAlarm": number,
"consecutiveDatapointsToClear": number,
"durationSeconds": number,
"mlDetectionConfig": {
"confidenceLevel": "string"
},
"statisticalThreshold": {
"statistic": "string"
},
"value": {
"cidrs": [ "string" ],
"count": number,
"number": number,
"numbers": [ number ],
"ports": [ number ],
"strings": [ "string" ]
}
},
"metric": "string",
"metricDimension": {
"dimensionName": "string",
"operator": "string"
},
"name": "string",
"suppressAlerts": boolean
}
]
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

behaviors (p. 689)

Specifies the behaviors that, when violated by a device (thing), cause an alert.

Type: Array of Behavior (p. 854) objects

Array Members: Maximum number of 100 items.

689
 AWS IoT API Reference
ValidateSecurityProfileBehaviors

Required: Yes

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"valid": boolean,
"validationErrors": [
{
"errorMessage": "string"
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

valid (p. 690)

True if the behaviors were valid.

Type: Boolean
validationErrors (p. 690)

The list of any errors found in the behaviors.

Type: Array of ValidationError (p. 1068) 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

690
 AWS IoT API Reference
AWS IoT data

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT data

The following actions are supported by AWS IoT data:

• DeleteThingShadow (p. 692)

• GetRetainedMessage (p. 695)
• GetThingShadow (p. 698)
• ListNamedShadowsForThing (p. 701)
• ListRetainedMessages (p. 704)
• Publish (p. 707)
• UpdateThingShadow (p. 710)

691
 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. 692)

The name of the shadow.

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 692)

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. 692)

The state information, in JSON format.

692
 AWS IoT API Reference
DeleteThingShadow

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

UnsupportedDocumentEncodingException

The document encoding is not supported.

HTTP Status Code: 415

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

693
 AWS IoT API Reference
DeleteThingShadow

• AWS SDK for Ruby V3

694
 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. 695)

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. 695)

The Epoch date and time, in milliseconds, when the retained message was stored by AWS IoT.

Type: Long
payload (p. 695)

The Base64-encoded message payload of the retained message body.

695
 AWS IoT API Reference
GetRetainedMessage

Type: Base64-encoded binary data object

qos (p. 695)

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. 695)

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

696
 AWS IoT API Reference
GetRetainedMessage

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

697
 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. 698)

The name of the shadow.

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 698)

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. 698)

The state information, in JSON format.

698
 AWS IoT API Reference
GetThingShadow

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

HTTP Status Code: 405

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

UnsupportedDocumentEncodingException

The document encoding is not supported.

HTTP Status Code: 415

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

699
 AWS IoT API Reference
GetThingShadow

• AWS SDK for Ruby V3

700
 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. 701)

The token to retrieve the next set of results.

pageSize (p. 701)

The result page size.

Valid Range: Minimum value of 1. Maximum value of 100.

thingName (p. 701)

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.

701
 AWS IoT API Reference
ListNamedShadowsForThing

nextToken (p. 701)

The token to use to get the next set of results, or null if there are no additional results.

Type: String
results (p. 701)

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. 701)

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

702
 AWS IoT API Reference
ListNamedShadowsForThing

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

703
 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. 704)

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 200.

nextToken (p. 704)

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.

704
 AWS IoT API Reference
ListRetainedMessages

The following data is returned in JSON format by the service.

nextToken (p. 704)

The token for the next set of results, or null if there are no additional results.

Type: String
retainedTopics (p. 704)

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. 1076) 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

705
 AWS IoT API Reference
ListRetainedMessages

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

706
 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. 707)

A UTF-8 encoded string that describes the content of the publishing message.
correlationData (p. 707)

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. 707)

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. 707)

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. 707)

The Quality of Service (QoS) level. The default QoS level is 0.

Valid Range: Minimum value of 0. Maximum value of 1.

responseTopic (p. 707)

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.

707
 AWS IoT API Reference
Publish

retain (p. 707)

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. 707)

The name of the MQTT topic.

Required: Yes
userProperties (p. 707)

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. 707)

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

708
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

709
 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. 710)

The name of the shadow.

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9:_-]+
thingName (p. 710)

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. 710)

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.

710
 AWS IoT API Reference
UpdateThingShadow

The response returns the following as the HTTP body.

payload (p. 710)

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:

711
 AWS IoT API Reference
AWS IoT jobs data

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT jobs data

The following actions are supported by AWS IoT jobs data:

• DescribeJobExecution (p. 713)

• GetPendingJobExecutions (p. 716)
• StartNextPendingJobExecution (p. 719)
• UpdateJobExecution (p. 722)

712
 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. 713)

Optional. A number that identifies a particular job execution on a particular device. If not specified,
the latest job execution is returned.
includeJobDocument (p. 713)

Optional. Unless set to false, the response contains the job document. The default is true.
jobId (p. 713)

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. 713)

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. 713)

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

713
 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. 714)

Contains data about a job execution.

Type: JobExecution (p. 1078) 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.

714
 AWS IoT API Reference
DescribeJobExecution

HTTP Status Code: 503

TerminalStateException

The job is in a terminal state.

HTTP Status Code: 410

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

715
 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. 716)

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. 716)

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

716
 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. 716)

A list of JobExecutionSummary objects with status IN_PROGRESS.

Type: Array of JobExecutionSummary (p. 1082) objects

queuedJobs (p. 716)

A list of JobExecutionSummary objects with status QUEUED.

Type: Array of JobExecutionSummary (p. 1082) 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

717
 AWS IoT API Reference
GetPendingJobExecutions

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

718
 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. 719)

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. 719)

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. 719)

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.

719
 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. 719)

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. 720)

A JobExecution object.

Type: JobExecution (p. 1078) object

720
 AWS IoT API Reference
StartNextPendingJobExecution

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InvalidRequestException

The contents of the request were invalid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

721
 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. 722)

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. 722)

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. 722)

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

722
 AWS IoT API Reference
UpdateJobExecution

Request Body
The request accepts the following data in JSON format.

executionNumber (p. 722)

Optional. A number that identifies a particular job execution on a particular device.

Type: Long

Required: No
expectedVersion (p. 722)

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. 722)

Optional. When set to true, the response contains the job document. The default is false.

Type: Boolean

Required: No
includeJobExecutionState (p. 722)

Optional. When included and set to true, the response contains the JobExecutionState data. The
default is false.

Type: Boolean

Required: No
status (p. 722)

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. 722)

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.

723
 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. 722)

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. 724)

A JobExecutionState object.

Type: JobExecutionState (p. 1081) object

jobDocument (p. 724)

The contents of the Job Documents.

Type: String

Length Constraints: Maximum length of 32768.

724
 AWS IoT API Reference
AWS IoT Core Device Advisor

Errors
CertificateValidationException

The certificate is invalid.

HTTP Status Code: 400

InvalidRequestException

The contents of the request were invalid.

HTTP Status Code: 400

InvalidStateTransitionException

An update attempted to change the job execution to a state that is invalid because of the job
execution's current state (for example, an attempt to change a request in state SUCCESS to state
IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

HTTP Status Code: 409

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT Core Device Advisor

The following actions are supported by AWS IoT Core Device Advisor:

725
 AWS IoT API Reference
AWS IoT Core Device Advisor

• CreateSuiteDefinition (p. 727)

• DeleteSuiteDefinition (p. 730)
• GetEndpoint (p. 732)
• GetSuiteDefinition (p. 734)
• GetSuiteRun (p. 737)
• GetSuiteRunReport (p. 741)
• ListSuiteDefinitions (p. 743)
• ListSuiteRuns (p. 745)
• ListTagsForResource (p. 748)
• StartSuiteRun (p. 750)
• StopSuiteRun (p. 753)
• TagResource (p. 755)
• UntagResource (p. 757)
• UpdateSuiteDefinition (p. 759)

726
 AWS IoT API Reference
CreateSuiteDefinition

CreateSuiteDefinition
Service: AWS IoT Core Device Advisor

Creates a Device Advisor test suite.

Requires permission to access the CreateSuiteDefinition action.

Request Syntax
POST /suiteDefinitions HTTP/1.1
Content-type: application/json

{
"suiteDefinitionConfiguration": {
"devicePermissionRoleArn": "string",
"devices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"rootGroup": "string",
"suiteDefinitionName": "string"
},
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request accepts the following data in JSON format.

suiteDefinitionConfiguration (p. 727)

Creates a Device Advisor test suite with suite definition configuration.

Type: SuiteDefinitionConfiguration (p. 1086) object

Required: No
tags (p. 727)

The tags to be attached to the suite definition.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

727
 AWS IoT API Reference
CreateSuiteDefinition

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"createdAt": number,
"suiteDefinitionArn": "string",
"suiteDefinitionId": "string",
"suiteDefinitionName": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

createdAt (p. 728)

Creates a Device Advisor test suite with TimeStamp of when it was created.

Type: Timestamp
suiteDefinitionArn (p. 728)

Creates a Device Advisor test suite with Amazon Resource Name (ARN).

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteDefinitionId (p. 728)

Creates a Device Advisor test suite with suite UUID.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionName (p. 728)

Creates a Device Advisor test suite with suite definition name.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Errors
InternalServerException

Sends an Internal Failure exception.

HTTP Status Code: 500

ValidationException

Sends a validation exception.

HTTP Status Code: 400

728
 AWS IoT API Reference
CreateSuiteDefinition

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

729
 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. 730)

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

730
 AWS IoT API Reference
DeleteSuiteDefinition

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

731
 AWS IoT API Reference
GetEndpoint

GetEndpoint
Service: AWS IoT Core Device Advisor

Gets information about an Device Advisor endpoint.

Request Syntax
GET /endpoint?certificateArn=certificateArn&thingArn=thingArn HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

certificateArn (p. 732)

The certificate ARN of the device. This is an optional parameter.

Length Constraints: Minimum length of 20. Maximum length of 2048.

thingArn (p. 732)

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.

endpoint (p. 732)

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.

732
 AWS IoT API Reference
GetEndpoint

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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

733
 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. 734)

Suite definition ID of the test suite to get.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteDefinitionVersion (p. 734)

Suite definition version of the test suite to get.

Length Constraints: Minimum length of 2. Maximum length of 255.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"createdAt": number,
"lastModifiedAt": number,
"latestVersion": "string",
"suiteDefinitionArn": "string",
"suiteDefinitionConfiguration": {
"devicePermissionRoleArn": "string",
"devices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"rootGroup": "string",
"suiteDefinitionName": "string"
},
"suiteDefinitionId": "string",
"suiteDefinitionVersion": "string",

734
 AWS IoT API Reference
GetSuiteDefinition

"tags": {
"string" : "string"
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

createdAt (p. 734)

Date (in Unix epoch time) when the suite definition was created.

Type: Timestamp
lastModifiedAt (p. 734)

Date (in Unix epoch time) when the suite definition was last modified.

Type: Timestamp
latestVersion (p. 734)

Latest suite definition version of the suite definition.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

suiteDefinitionArn (p. 734)

The ARN of the suite definition.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteDefinitionConfiguration (p. 734)

Suite configuration of the suite definition.

Type: SuiteDefinitionConfiguration (p. 1086) object

suiteDefinitionId (p. 734)

Suite definition ID of the suite definition.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionVersion (p. 734)

Suite definition version of the suite definition.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

tags (p. 734)

Tags attached to the suite definition.

Type: String to string map

735
 AWS IoT API Reference
GetSuiteDefinition

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Errors
InternalServerException

Sends 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

736
 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. 737)

Suite definition ID for the test suite run.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteRunId (p. 737)

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",
"thingArn": "string"
},
"selectedTestList": [ "string" ]
},
"suiteRunId": "string",
"tags": {

737
 AWS IoT API Reference
GetSuiteRun

"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",
"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. 737)

Date (in Unix epoch time) when the test suite run ended.

Type: Timestamp
errorReason (p. 737)

Error reason for any test suite run failure.

Type: String
startTime (p. 737)

Date (in Unix epoch time) when the test suite run started.

Type: Timestamp
status (p. 737)

Status for the test suite run.

Type: String

Valid Values: PASS | FAIL | CANCELED | PENDING | RUNNING | STOPPING | STOPPED |

PASS_WITH_WARNINGS | ERROR
suiteDefinitionId (p. 737)

Suite definition ID for the test suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

738
 AWS IoT API Reference
GetSuiteRun

suiteDefinitionVersion (p. 737)

Suite definition version for the test suite run.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

suiteRunArn (p. 737)

The ARN of the suite run.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteRunConfiguration (p. 737)

Suite run configuration for the test suite run.

Type: SuiteRunConfiguration (p. 1090) object

suiteRunId (p. 737)

Suite run ID for the test suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

tags (p. 737)

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. 737)

Test results for the test suite run.

Type: TestResult (p. 1095) object

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.

739
 AWS IoT API Reference
GetSuiteRun

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

740
 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. 741)

Suite definition ID of the test suite.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: Yes
suiteRunId (p. 741)

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. 741)

Download URL of the qualification report.

Type: String

741
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

742
 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. 743)

The maximum number of results to return at once.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken (p. 743)

A token used to get the next set of results.

Length Constraints: Maximum length of 2000.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"nextToken": "string",
"suiteDefinitionInformationList": [
{
"createdAt": number,
"defaultDevices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"suiteDefinitionId": "string",
"suiteDefinitionName": "string"
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

743
 AWS IoT API Reference
ListSuiteDefinitions

The following data is returned in JSON format by the service.

nextToken (p. 743)

A token used to get the next set of results.

Type: String

Length Constraints: Maximum length of 2000.

suiteDefinitionInformationList (p. 743)

An array of objects that provide summaries of information about the suite definitions in the list.

Type: Array of SuiteDefinitionInformation (p. 1088) 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

744
 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. 745)

The maximum number of results to return at once.

Valid Range: Minimum value of 1. Maximum value of 50.

nextToken (p. 745)

A token to retrieve the next set of results.

Length Constraints: Maximum length of 2000.

suiteDefinitionId (p. 745)

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. 745)

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,

745
 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. 745)

A token to retrieve the next set of results.

Type: String

Length Constraints: Maximum length of 2000.

suiteRunsList (p. 745)

An array of objects that provide summaries of information about the suite runs in the list.

Type: Array of SuiteRunInformation (p. 1091) 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
• AWS SDK for PHP V3
• AWS SDK for Python

746
 AWS IoT API Reference
ListSuiteRuns

• AWS SDK for Ruby V3

747
 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. 748)

The ARN of the IoT Device Advisor resource.

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"tags": {
"string" : "string"
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

tags (p. 748)

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.

748
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

749
 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",
"thingArn": "string"
},
"selectedTestList": [ "string" ]
},
"tags": {
"string" : "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 750)

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. 750)

Suite definition version of the test suite.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 255.

Required: No
suiteRunConfiguration (p. 750)

Suite run configuration.

Type: SuiteRunConfiguration (p. 1090) object

750
 AWS IoT API Reference
StartSuiteRun

Required: No
tags (p. 750)

The tags to be attached to the suite run.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

{
"createdAt": number,
"suiteRunArn": "string",
"suiteRunId": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

createdAt (p. 751)

Starts a Device Advisor test suite run based on suite create time.

Type: Timestamp
suiteRunArn (p. 751)

Amazon Resource Name (ARN) of the started suite run.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteRunId (p. 751)

Suite Run ID of the started suite run.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Errors
ConflictException

Sends a Conflict Exception.

751
 AWS IoT API Reference
StartSuiteRun

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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

752
 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. 753)

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. 753)

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

753
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

754
 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. 755)

The resource ARN of an IoT Device Advisor resource.

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes

Request Body
The request accepts the following data in JSON format.

tags (p. 755)

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.

755
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

756
 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. 757)

The resource ARN of an IoT Device Advisor resource.

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: Yes
tagKeys (p. 757)

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.

757
 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
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

758
 AWS IoT API Reference
UpdateSuiteDefinition

UpdateSuiteDefinition
Service: AWS IoT Core Device Advisor

Updates a Device Advisor test suite.

Requires permission to access the UpdateSuiteDefinition action.

Request Syntax
PATCH /suiteDefinitions/suiteDefinitionId HTTP/1.1
Content-type: application/json

{
"suiteDefinitionConfiguration": {
"devicePermissionRoleArn": "string",
"devices": [
{
"certificateArn": "string",
"thingArn": "string"
}
],
"intendedForQualification": boolean,
"rootGroup": "string",
"suiteDefinitionName": "string"
}
}

URI Request Parameters

The request uses the following URI parameters.

suiteDefinitionId (p. 759)

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. 759)

Updates a Device Advisor test suite with suite definition configuration.

Type: SuiteDefinitionConfiguration (p. 1086) object

Required: No

Response Syntax
HTTP/1.1 200
Content-type: application/json

759
 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. 759)

Timestamp of when the test suite was created.

Type: Timestamp
lastUpdatedAt (p. 759)

Timestamp of when the test suite was updated.

Type: Timestamp
suiteDefinitionArn (p. 759)

Amazon Resource Name (ARN) of the updated test suite.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

suiteDefinitionId (p. 759)

Suite definition ID of the updated test suite.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

suiteDefinitionName (p. 759)

Suite definition name of the updated test suite.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

suiteDefinitionVersion (p. 759)

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.

760
 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
• 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. 762)

• DeleteApplication (p. 765)
• DescribeApplication (p. 767)
• ListApplications (p. 771)
• ListTagsForResource (p. 773)
• TagResource (p. 775)
• UntagResource (p. 777)
• UpdateApplication (p. 779)

761
 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. 762)

An optional description of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^[ -~]*$

Required: No
applicationName (p. 762)

The name of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[ -~]*$

Required: Yes
clientToken (p. 762)

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.

762
 AWS IoT API Reference
CreateApplication

Pattern: ^[a-zA-Z0-9-_]+$

Required: No
roleArn (p. 762)

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. 762)

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. 763)

The ARN of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Pattern: ^arn:[!-~]+$

763
 AWS IoT API Reference
CreateApplication

applicationId (p. 763)

The unique Id of the web application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

A limit has been exceeded.

HTTP Status Code: 410

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

764
 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. 765)

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. 765)

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.

765
 AWS IoT API Reference
DeleteApplication

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

766
 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. 767)

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.

767
 AWS IoT API Reference
DescribeApplication

applicationArn (p. 767)

The ARN of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

Pattern: ^arn:[!-~]+$
applicationCreationDate (p. 767)

The date (in Unix epoch time) when the application was created.

Type: Long
applicationDescription (p. 767)

An optional description of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^[ -~]*$
applicationId (p. 767)

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. 767)

The date (in Unix epoch time) when the application was last updated.

Type: Long
applicationName (p. 767)

The name of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[ -~]*$
applicationState (p. 767)

The current state of the web application.

Type: String

Valid Values: CREATING | DELETING | ACTIVE | CREATE_FAILED | DELETE_FAILED

applicationUrl (p. 767)

The URL of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

768
 AWS IoT API Reference
DescribeApplication

Pattern: ^https\://\S+$
errorMessage (p. 767)

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. 767)

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. 767)

The Id of the single sign-on client that you use to authenticate and authorize users on the web
application.

Type: String
tags (p. 767)

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

769
 AWS IoT API Reference
DescribeApplication

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

770
 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. 771)

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. 771)

An array of objects that provide summaries of information about the web applications in the list.

Type: Array of ApplicationSummary (p. 1096) objects

771
 AWS IoT API Reference
ListApplications

nextToken (p. 771)

A token used to get the next set of results.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^[A-Za-z0-9+/=]+$

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

772
 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. 773)

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. 773)

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.

773
 AWS IoT API Reference
ListTagsForResource

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

774
 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. 775)

The ARN of the resource.

Required: Yes

Request Body
The request accepts the following data in JSON format.

tags (p. 775)

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.

775
 AWS IoT API Reference
TagResource

Errors
InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

776
 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. 777)

The ARN of the resource.

Required: Yes
tagKeys (p. 777)

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

777
 AWS IoT API Reference
UntagResource

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

778
 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. 779)

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. 779)

An optional description of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^[ -~]*$

Required: No
applicationName (p. 779)

The name of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[ -~]*$

Required: No

779
 AWS IoT API Reference
UpdateApplication

clientToken (p. 779)

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

780
 AWS IoT API Reference
AWS IoT Secure Tunneling

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

AWS IoT Secure Tunneling

The following actions are supported by AWS IoT Secure Tunneling:

• CloseTunnel (p. 782)

• DescribeTunnel (p. 784)
• ListTagsForResource (p. 786)
• ListTunnels (p. 788)
• OpenTunnel (p. 790)
• RotateTunnelAccessToken (p. 793)
• TagResource (p. 796)
• UntagResource (p. 798)

781
 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. 1106).

The request accepts the following data in JSON format.

delete (p. 782)

When set to true, AWS IoT Secure Tunneling deletes the tunnel data immediately.

Type: Boolean

Required: No
tunnelId (p. 782)

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:

782
 AWS IoT API Reference
CloseTunnel

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

783
 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. 1106).

The request accepts the following data in JSON format.

tunnelId (p. 784)

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

784
 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. 784)

The tunnel being described.

Type: Tunnel (p. 1102) object

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

785
 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. 1106).

The request accepts the following data in JSON format.

resourceArn (p. 786)

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. 786)

The tags for the specified resource.

Type: Array of Tag (p. 1100) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

786
 AWS IoT API Reference
ListTagsForResource

Errors
ResourceNotFoundException

Thrown when an operation is attempted on a resource that does not exist.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

787
 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. 1106).

The request accepts the following data in JSON format.

maxResults (p. 788)

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. 788)

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. 788)

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
{

788
 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. 788)

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. 788)

A short description of the tunnels in an AWS account.

Type: Array of TunnelSummary (p. 1104) objects

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

789
 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. 1106).

The request accepts the following data in JSON format.

description (p. 790)

A short text description of the tunnel.

Type: String

Pattern: [^\p{C}]{1,2048}

Required: No
destinationConfig (p. 790)

The destination configuration for the OpenTunnel request.

Type: DestinationConfig (p. 1099) object

Required: No
tags (p. 790)

A collection of tag metadata.

Type: Array of Tag (p. 1100) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

Required: No

790
 AWS IoT API Reference
OpenTunnel

timeoutConfig (p. 790)

Timeout configuration for a tunnel.

Type: TimeoutConfig (p. 1101) 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. 791)

The access token the destination local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
sourceAccessToken (p. 791)

The access token the source local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
tunnelArn (p. 791)

The Amazon Resource Name for the tunnel.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1600.

tunnelId (p. 791)

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

791
 AWS IoT API Reference
OpenTunnel

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

792
 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. 1106).

The request accepts the following data in JSON format.

clientMode (p. 793)

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. 793)

The destination configuration.

Type: DestinationConfig (p. 1099) object

Required: No
tunnelId (p. 793)

The tunnel for which you want to rotate the access tokens.

Type: String

Pattern: [a-zA-Z0-9_\-+=:]{1,128}

Required: Yes

793
 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. 794)

The client access token that the destination local proxy uses to connect to AWS IoT Secure
Tunneling.

Type: String
sourceAccessToken (p. 794)

The client access token that the source local proxy uses to connect to AWS IoT Secure Tunneling.

Type: String
tunnelArn (p. 794)

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
• AWS SDK for PHP V3
• AWS SDK for Python

794
 AWS IoT API Reference
RotateTunnelAccessToken

• AWS SDK for Ruby V3

795
 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. 1106).

The request accepts the following data in JSON format.

resourceArn (p. 796)

The ARN of the resource.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes
tags (p. 796)

The tags for the resource.

Type: Array of Tag (p. 1100) 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

796
 AWS IoT API Reference
TagResource

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

797
 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. 1106).

The request accepts the following data in JSON format.

resourceArn (p. 798)

The resource ARN.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1011.

Required: Yes
tagKeys (p. 798)

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:

798
 AWS IoT API Reference
UntagResource

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3

799
 AWS IoT API Reference

Data Types
The following data types are supported by AWS IoT:

• AbortConfig (p. 810)

• AbortCriteria (p. 811)
• Action (p. 813)
• ActiveViolation (p. 817)
• AddThingsToThingGroupParams (p. 819)
• AggregationType (p. 820)
• AlertTarget (p. 821)
• Allowed (p. 822)
• AssetPropertyTimestamp (p. 823)
• AssetPropertyValue (p. 824)
• AssetPropertyVariant (p. 825)
• AttributePayload (p. 826)
• AuditCheckConfiguration (p. 827)
• AuditCheckDetails (p. 828)
• AuditFinding (p. 830)
• AuditMitigationActionExecutionMetadata (p. 832)
• AuditMitigationActionsTaskMetadata (p. 834)
• AuditMitigationActionsTaskTarget (p. 835)
• AuditNotificationTarget (p. 836)
• AuditSuppression (p. 837)
• AuditTaskMetadata (p. 839)
• AuthInfo (p. 840)
• AuthorizerConfig (p. 841)
• AuthorizerDescription (p. 842)
• AuthorizerSummary (p. 844)
• AuthResult (p. 845)
• AwsJobAbortConfig (p. 846)
• AwsJobAbortCriteria (p. 847)
• AwsJobExecutionsRolloutConfig (p. 849)
• AwsJobExponentialRolloutRate (p. 850)
• AwsJobPresignedUrlConfig (p. 851)
• AwsJobRateIncreaseCriteria (p. 852)
• AwsJobTimeoutConfig (p. 853)
• Behavior (p. 854)
• BehaviorCriteria (p. 856)
• BehaviorModelTrainingSummary (p. 858)
• BillingGroupMetadata (p. 860)
• BillingGroupProperties (p. 861)
• Bucket (p. 862)
• BucketsAggregationType (p. 863)

800
 AWS IoT API Reference

• CACertificate (p. 864)

• CACertificateDescription (p. 865)
• Certificate (p. 868)
• CertificateDescription (p. 870)
• CertificateValidity (p. 873)
• CloudwatchAlarmAction (p. 874)
• CloudwatchLogsAction (p. 875)
• CloudwatchMetricAction (p. 876)
• CodeSigning (p. 878)
• CodeSigningCertificateChain (p. 879)
• CodeSigningSignature (p. 880)
• Configuration (p. 881)
• CustomCodeSigning (p. 882)
• Denied (p. 883)
• Destination (p. 884)
• DetectMitigationActionExecution (p. 885)
• DetectMitigationActionsTaskStatistics (p. 887)
• DetectMitigationActionsTaskSummary (p. 888)
• DetectMitigationActionsTaskTarget (p. 890)
• DocumentParameter (p. 891)
• DomainConfigurationSummary (p. 893)
• DynamoDBAction (p. 894)
• DynamoDBv2Action (p. 896)
• EffectivePolicy (p. 897)
• ElasticsearchAction (p. 898)
• EnableIoTLoggingParams (p. 900)
• ErrorInfo (p. 901)
• ExplicitDeny (p. 902)
• ExponentialRolloutRate (p. 903)
• Field (p. 904)
• FileLocation (p. 905)
• FirehoseAction (p. 906)
• FleetMetricNameAndArn (p. 907)
• GroupNameAndArn (p. 908)
• HttpAction (p. 909)
• HttpActionHeader (p. 911)
• HttpAuthorization (p. 912)
• HttpContext (p. 913)
• HttpUrlDestinationConfiguration (p. 914)
• HttpUrlDestinationProperties (p. 915)
• HttpUrlDestinationSummary (p. 916)
• ImplicitDeny (p. 917)
• IndexingFilter (p. 918)
• IotAnalyticsAction (p. 919)
• IotEventsAction (p. 920)
• IotSiteWiseAction (p. 922)

801
 AWS IoT API Reference

• IssuerCertificateIdentifier (p. 923)

• Job (p. 924)
• JobExecution (p. 929)
• JobExecutionsRetryConfig (p. 931)
• JobExecutionsRolloutConfig (p. 932)
• JobExecutionStatusDetails (p. 933)
• JobExecutionSummary (p. 934)
• JobExecutionSummaryForJob (p. 936)
• JobExecutionSummaryForThing (p. 937)
• JobProcessDetails (p. 938)
• JobSummary (p. 940)
• JobTemplateSummary (p. 942)
• KafkaAction (p. 944)
• KeyPair (p. 945)
• KinesisAction (p. 946)
• LambdaAction (p. 947)
• LocationAction (p. 948)
• LocationTimestamp (p. 950)
• LoggingOptionsPayload (p. 951)
• LogTarget (p. 952)
• LogTargetConfiguration (p. 953)
• MachineLearningDetectionConfig (p. 954)
• ManagedJobTemplateSummary (p. 955)
• MetricDatum (p. 957)
• MetricDimension (p. 958)
• MetricToRetain (p. 959)
• MetricValue (p. 960)
• MitigationAction (p. 962)
• MitigationActionIdentifier (p. 963)
• MitigationActionParams (p. 964)
• MqttContext (p. 966)
• MqttHeaders (p. 967)
• NonCompliantResource (p. 969)
• OpenSearchAction (p. 970)
• OTAUpdateFile (p. 971)
• OTAUpdateInfo (p. 973)
• OTAUpdateSummary (p. 976)
• OutgoingCertificate (p. 977)
• PercentPair (p. 979)
• Policy (p. 980)
• PolicyVersion (p. 981)
• PolicyVersionIdentifier (p. 982)
• PresignedUrlConfig (p. 983)
• ProvisioningHook (p. 984)
• ProvisioningTemplateSummary (p. 985)
• ProvisioningTemplateVersionSummary (p. 987)

802
 AWS IoT API Reference

• PublishFindingToSnsParams (p. 988)

• PutAssetPropertyValueEntry (p. 989)
• PutItemInput (p. 991)
• RateIncreaseCriteria (p. 992)
• RegistrationConfig (p. 993)
• RelatedResource (p. 994)
• ReplaceDefaultPolicyVersionParams (p. 995)
• RepublishAction (p. 996)
• ResourceIdentifier (p. 997)
• RetryCriteria (p. 999)
• RoleAliasDescription (p. 1000)
• S3Action (p. 1002)
• S3Destination (p. 1003)
• S3Location (p. 1004)
• SalesforceAction (p. 1005)
• ScheduledAuditMetadata (p. 1006)
• SchedulingConfig (p. 1008)
• SecurityProfileIdentifier (p. 1009)
• SecurityProfileTarget (p. 1010)
• SecurityProfileTargetMapping (p. 1011)
• ServerCertificateSummary (p. 1012)
• SigningProfileParameter (p. 1013)
• SigV4Authorization (p. 1014)
• SnsAction (p. 1015)
• SqsAction (p. 1016)
• StartSigningJobParameter (p. 1017)
• StatisticalThreshold (p. 1018)
• Statistics (p. 1019)
• StepFunctionsAction (p. 1021)
• Stream (p. 1022)
• StreamFile (p. 1023)
• StreamInfo (p. 1024)
• StreamSummary (p. 1026)
• Tag (p. 1027)
• TaskStatistics (p. 1028)
• TaskStatisticsForAuditCheck (p. 1030)
• TermsAggregation (p. 1031)
• ThingAttribute (p. 1032)
• ThingConnectivity (p. 1034)
• ThingDocument (p. 1035)
• ThingGroupDocument (p. 1037)
• ThingGroupIndexingConfiguration (p. 1039)
• ThingGroupMetadata (p. 1040)
• ThingGroupProperties (p. 1041)
• ThingIndexingConfiguration (p. 1042)
• ThingTypeDefinition (p. 1044)

803
 AWS IoT API Reference

• ThingTypeMetadata (p. 1045)

• ThingTypeProperties (p. 1046)
• TimeoutConfig (p. 1047)
• TimestreamAction (p. 1048)
• TimestreamDimension (p. 1050)
• TimestreamTimestamp (p. 1051)
• TlsContext (p. 1052)
• TopicRule (p. 1053)
• TopicRuleDestination (p. 1055)
• TopicRuleDestinationConfiguration (p. 1057)
• TopicRuleDestinationSummary (p. 1058)
• TopicRuleListItem (p. 1060)
• TopicRulePayload (p. 1061)
• TransferData (p. 1063)
• UpdateCACertificateParams (p. 1065)
• UpdateDeviceCertificateParams (p. 1066)
• UserProperty (p. 1067)
• ValidationError (p. 1068)
• ViolationEvent (p. 1069)
• ViolationEventAdditionalInfo (p. 1071)
• ViolationEventOccurrenceRange (p. 1072)
• VpcDestinationConfiguration (p. 1073)
• VpcDestinationProperties (p. 1074)
• VpcDestinationSummary (p. 1075)

The following data types are supported by AWS IoT data:

• RetainedMessageSummary (p. 1076)

The following data types are supported by AWS IoT jobs data:

• JobExecution (p. 1078)

• JobExecutionState (p. 1081)
• JobExecutionSummary (p. 1082)

The following data types are supported by AWS IoT Core Device Advisor:

• DeviceUnderTest (p. 1084)

• GroupResult (p. 1085)
• SuiteDefinitionConfiguration (p. 1086)
• SuiteDefinitionInformation (p. 1088)
• SuiteRunConfiguration (p. 1090)
• SuiteRunInformation (p. 1091)
• TestCaseRun (p. 1093)
• TestResult (p. 1095)

The following data types are supported by AWS IoT Fleet Hub:

804
 AWS IoT API Reference
AWS IoT

• ApplicationSummary (p. 1096)

The following data types are supported by AWS IoT Secure Tunneling:

• ConnectionState (p. 1098)

• DestinationConfig (p. 1099)
• Tag (p. 1100)
• TimeoutConfig (p. 1101)
• Tunnel (p. 1102)
• TunnelSummary (p. 1104)

AWS IoT
The following data types are supported by AWS IoT:

• AbortConfig (p. 810)

• AbortCriteria (p. 811)
• Action (p. 813)
• ActiveViolation (p. 817)
• AddThingsToThingGroupParams (p. 819)
• AggregationType (p. 820)
• AlertTarget (p. 821)
• Allowed (p. 822)
• AssetPropertyTimestamp (p. 823)
• AssetPropertyValue (p. 824)
• AssetPropertyVariant (p. 825)
• AttributePayload (p. 826)
• AuditCheckConfiguration (p. 827)
• AuditCheckDetails (p. 828)
• AuditFinding (p. 830)
• AuditMitigationActionExecutionMetadata (p. 832)
• AuditMitigationActionsTaskMetadata (p. 834)
• AuditMitigationActionsTaskTarget (p. 835)
• AuditNotificationTarget (p. 836)
• AuditSuppression (p. 837)
• AuditTaskMetadata (p. 839)
• AuthInfo (p. 840)
• AuthorizerConfig (p. 841)
• AuthorizerDescription (p. 842)
• AuthorizerSummary (p. 844)
• AuthResult (p. 845)
• AwsJobAbortConfig (p. 846)
• AwsJobAbortCriteria (p. 847)
• AwsJobExecutionsRolloutConfig (p. 849)
• AwsJobExponentialRolloutRate (p. 850)
• AwsJobPresignedUrlConfig (p. 851)

805
 AWS IoT API Reference
AWS IoT

• AwsJobRateIncreaseCriteria (p. 852)

• AwsJobTimeoutConfig (p. 853)
• Behavior (p. 854)
• BehaviorCriteria (p. 856)
• BehaviorModelTrainingSummary (p. 858)
• BillingGroupMetadata (p. 860)
• BillingGroupProperties (p. 861)
• Bucket (p. 862)
• BucketsAggregationType (p. 863)
• CACertificate (p. 864)
• CACertificateDescription (p. 865)
• Certificate (p. 868)
• CertificateDescription (p. 870)
• CertificateValidity (p. 873)
• CloudwatchAlarmAction (p. 874)
• CloudwatchLogsAction (p. 875)
• CloudwatchMetricAction (p. 876)
• CodeSigning (p. 878)
• CodeSigningCertificateChain (p. 879)
• CodeSigningSignature (p. 880)
• Configuration (p. 881)
• CustomCodeSigning (p. 882)
• Denied (p. 883)
• Destination (p. 884)
• DetectMitigationActionExecution (p. 885)
• DetectMitigationActionsTaskStatistics (p. 887)
• DetectMitigationActionsTaskSummary (p. 888)
• DetectMitigationActionsTaskTarget (p. 890)
• DocumentParameter (p. 891)
• DomainConfigurationSummary (p. 893)
• DynamoDBAction (p. 894)
• DynamoDBv2Action (p. 896)
• EffectivePolicy (p. 897)
• ElasticsearchAction (p. 898)
• EnableIoTLoggingParams (p. 900)
• ErrorInfo (p. 901)
• ExplicitDeny (p. 902)
• ExponentialRolloutRate (p. 903)
• Field (p. 904)
• FileLocation (p. 905)
• FirehoseAction (p. 906)
• FleetMetricNameAndArn (p. 907)
• GroupNameAndArn (p. 908)
• HttpAction (p. 909)
• HttpActionHeader (p. 911)
• HttpAuthorization (p. 912)

806
 AWS IoT API Reference
AWS IoT

• HttpContext (p. 913)

• HttpUrlDestinationConfiguration (p. 914)
• HttpUrlDestinationProperties (p. 915)
• HttpUrlDestinationSummary (p. 916)
• ImplicitDeny (p. 917)
• IndexingFilter (p. 918)
• IotAnalyticsAction (p. 919)
• IotEventsAction (p. 920)
• IotSiteWiseAction (p. 922)
• IssuerCertificateIdentifier (p. 923)
• Job (p. 924)
• JobExecution (p. 929)
• JobExecutionsRetryConfig (p. 931)
• JobExecutionsRolloutConfig (p. 932)
• JobExecutionStatusDetails (p. 933)
• JobExecutionSummary (p. 934)
• JobExecutionSummaryForJob (p. 936)
• JobExecutionSummaryForThing (p. 937)
• JobProcessDetails (p. 938)
• JobSummary (p. 940)
• JobTemplateSummary (p. 942)
• KafkaAction (p. 944)
• KeyPair (p. 945)
• KinesisAction (p. 946)
• LambdaAction (p. 947)
• LocationAction (p. 948)
• LocationTimestamp (p. 950)
• LoggingOptionsPayload (p. 951)
• LogTarget (p. 952)
• LogTargetConfiguration (p. 953)
• MachineLearningDetectionConfig (p. 954)
• ManagedJobTemplateSummary (p. 955)
• MetricDatum (p. 957)
• MetricDimension (p. 958)
• MetricToRetain (p. 959)
• MetricValue (p. 960)
• MitigationAction (p. 962)
• MitigationActionIdentifier (p. 963)
• MitigationActionParams (p. 964)
• MqttContext (p. 966)
• MqttHeaders (p. 967)
• NonCompliantResource (p. 969)
• OpenSearchAction (p. 970)
• OTAUpdateFile (p. 971)
• OTAUpdateInfo (p. 973)
• OTAUpdateSummary (p. 976)

807
 AWS IoT API Reference
AWS IoT

• OutgoingCertificate (p. 977)

• PercentPair (p. 979)
• Policy (p. 980)
• PolicyVersion (p. 981)
• PolicyVersionIdentifier (p. 982)
• PresignedUrlConfig (p. 983)
• ProvisioningHook (p. 984)
• ProvisioningTemplateSummary (p. 985)
• ProvisioningTemplateVersionSummary (p. 987)
• PublishFindingToSnsParams (p. 988)
• PutAssetPropertyValueEntry (p. 989)
• PutItemInput (p. 991)
• RateIncreaseCriteria (p. 992)
• RegistrationConfig (p. 993)
• RelatedResource (p. 994)
• ReplaceDefaultPolicyVersionParams (p. 995)
• RepublishAction (p. 996)
• ResourceIdentifier (p. 997)
• RetryCriteria (p. 999)
• RoleAliasDescription (p. 1000)
• S3Action (p. 1002)
• S3Destination (p. 1003)
• S3Location (p. 1004)
• SalesforceAction (p. 1005)
• ScheduledAuditMetadata (p. 1006)
• SchedulingConfig (p. 1008)
• SecurityProfileIdentifier (p. 1009)
• SecurityProfileTarget (p. 1010)
• SecurityProfileTargetMapping (p. 1011)
• ServerCertificateSummary (p. 1012)
• SigningProfileParameter (p. 1013)
• SigV4Authorization (p. 1014)
• SnsAction (p. 1015)
• SqsAction (p. 1016)
• StartSigningJobParameter (p. 1017)
• StatisticalThreshold (p. 1018)
• Statistics (p. 1019)
• StepFunctionsAction (p. 1021)
• Stream (p. 1022)
• StreamFile (p. 1023)
• StreamInfo (p. 1024)
• StreamSummary (p. 1026)
• Tag (p. 1027)
• TaskStatistics (p. 1028)
• TaskStatisticsForAuditCheck (p. 1030)
• TermsAggregation (p. 1031)

808
 AWS IoT API Reference
AWS IoT

• ThingAttribute (p. 1032)

• ThingConnectivity (p. 1034)
• ThingDocument (p. 1035)
• ThingGroupDocument (p. 1037)
• ThingGroupIndexingConfiguration (p. 1039)
• ThingGroupMetadata (p. 1040)
• ThingGroupProperties (p. 1041)
• ThingIndexingConfiguration (p. 1042)
• ThingTypeDefinition (p. 1044)
• ThingTypeMetadata (p. 1045)
• ThingTypeProperties (p. 1046)
• TimeoutConfig (p. 1047)
• TimestreamAction (p. 1048)
• TimestreamDimension (p. 1050)
• TimestreamTimestamp (p. 1051)
• TlsContext (p. 1052)
• TopicRule (p. 1053)
• TopicRuleDestination (p. 1055)
• TopicRuleDestinationConfiguration (p. 1057)
• TopicRuleDestinationSummary (p. 1058)
• TopicRuleListItem (p. 1060)
• TopicRulePayload (p. 1061)
• TransferData (p. 1063)
• UpdateCACertificateParams (p. 1065)
• UpdateDeviceCertificateParams (p. 1066)
• UserProperty (p. 1067)
• ValidationError (p. 1068)
• ViolationEvent (p. 1069)
• ViolationEventAdditionalInfo (p. 1071)
• ViolationEventOccurrenceRange (p. 1072)
• VpcDestinationConfiguration (p. 1073)
• VpcDestinationProperties (p. 1074)
• VpcDestinationSummary (p. 1075)

809
 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. 811) 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

810
 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

811
AWS IoT API Reference
AbortCriteria

812
 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. 874) object

Required: No
cloudwatchLogs

Send data to CloudWatch Logs.

Type: CloudwatchLogsAction (p. 875) object

Required: No
cloudwatchMetric

Capture a CloudWatch metric.

Type: CloudwatchMetricAction (p. 876) object

Required: No
dynamoDB

Write to a DynamoDB table.

Type: DynamoDBAction (p. 894) 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. 896) 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. 898) object

Required: No
firehose

Write to an Amazon Kinesis Firehose stream.

813
 AWS IoT API Reference
Action

Type: FirehoseAction (p. 906) object

Required: No
http

Send data to an HTTPS endpoint.

Type: HttpAction (p. 909) object

Required: No
iotAnalytics

Sends message data to an AWS IoT Analytics channel.

Type: IotAnalyticsAction (p. 919) object

Required: No
iotEvents

Sends an input to an AWS IoT Events detector.

Type: IotEventsAction (p. 920) object

Required: No
iotSiteWise

Sends data from the MQTT message that triggered the rule to AWS IoT SiteWise asset properties.

Type: IotSiteWiseAction (p. 922) 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. 944) object

Required: No
kinesis

Write data to an Amazon Kinesis stream.

Type: KinesisAction (p. 946) object

Required: No
lambda

Invoke a Lambda function.

Type: LambdaAction (p. 947) 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. 948) object

814
 AWS IoT API Reference
Action

Required: No
openSearch

Write data to an Amazon OpenSearch Service domain.

Type: OpenSearchAction (p. 970) object

Required: No
republish

Publish to another MQTT topic.

Type: RepublishAction (p. 996) object

Required: No
s3

Write to an Amazon S3 bucket.

Type: S3Action (p. 1002) object

Required: No
salesforce

Send a message to a Salesforce IoT Cloud Input Stream.

Type: SalesforceAction (p. 1005) object

Required: No
sns

Publish to an Amazon SNS topic.

Type: SnsAction (p. 1015) object

Required: No
sqs

Publish to an Amazon SQS queue.

Type: SqsAction (p. 1016) object

Required: No
stepFunctions

Starts execution of a Step Functions state machine.

Type: StepFunctionsAction (p. 1021) 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. 1048) object

Required: No

815
 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

816
 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. 854) 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. 960) 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.

817
 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. 1071) 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

818
 AWS IoT API Reference
AddThingsToThingGroupParams

AddThingsToThingGroupParams
Service: AWS IoT

Parameters used when defining a mitigation action that move a set of things to a thing group.

Contents
overrideDynamicGroups

Specifies if this mitigation action can move the things that triggered the mitigation action even if
they are part of one or more dynamic thing groups.

Type: Boolean

Required: No
thingGroupNames

The list of groups to which you want to add the things that triggered the mitigation action. You can
add a thing to a maximum of 10 groups, but you can't add a thing to more than one group in the
same hierarchy.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

819
 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

820
 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

821
 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. 980) 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

822
 AWS IoT API Reference
AssetPropertyTimestamp

AssetPropertyTimestamp
Service: AWS IoT

An asset property timestamp entry containing the following information.

Contents
offsetInNanos

Optional. A string that contains the nanosecond time offset. Accepts substitution templates.

Type: String

Required: No
timeInSeconds

A string that contains the time in seconds since epoch. Accepts substitution templates.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

823
 AWS IoT API Reference
AssetPropertyValue

AssetPropertyValue
Service: AWS IoT

An asset property value entry containing the following information.

Contents
quality

Optional. A string that describes the quality of the value. Accepts substitution templates. Must be
GOOD, BAD, or UNCERTAIN.

Type: String

Required: No
timestamp

The asset property value timestamp.

Type: AssetPropertyTimestamp (p. 823) object

Required: Yes
value

The value of the asset property.

Type: AssetPropertyVariant (p. 825) 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

824
 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

825
 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

826
 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

827
 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

828
 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

829
 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. 969) 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

830
 AWS IoT API Reference
AuditFinding

Required: No
relatedResources

The list of related resources.

Type: Array of RelatedResource (p. 994) 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

831
 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.

832
 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

833
 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

834
 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

835
 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

836
 AWS IoT API Reference
AuditSuppression

AuditSuppression
Service: AWS IoT

Filters out specific findings of a Device Defender audit.

Contents
checkName

An audit check name. Checks must be enabled for your account. (Use
DescribeAccountAuditConfiguration to see the list of all checks, including those that are
enabled or use UpdateAccountAuditConfiguration to select which checks are enabled.)

Type: String

Required: Yes
description

The description of the audit suppression.

Type: String

Length Constraints: Maximum length of 1000.

Pattern: [\p{Graph}\x20]*

Required: No
expirationDate

The expiration date (epoch timestamp in seconds) that you want the suppression to adhere to.

Type: Timestamp

Required: No
resourceIdentifier

Information that identifies the noncompliant resource.

Type: ResourceIdentifier (p. 997) object

Required: Yes
suppressIndefinitely

Indicates whether a suppression should exist indefinitely or not.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2

837
 AWS IoT API Reference
AuditSuppression

• AWS SDK for Ruby V3

838
 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

839
 AWS IoT API Reference
AuthInfo

AuthInfo
Service: AWS IoT

A collection of authorization information.

Contents
actionType

The type of action for which the principal is being authorized.

Type: String

Valid Values: PUBLISH | SUBSCRIBE | RECEIVE | CONNECT

Required: No
resources

The resources for which the principal is being authorized to perform the specified action.

Type: Array of strings

Length Constraints: Maximum length of 2048.

Pattern: [\s\S]*

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

840
 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

841
 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

842
 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

843
 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

844
 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. 822) 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. 840) object

Required: No
denied

The policies and statements that denied the specified action.

Type: Denied (p. 883) 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

845
 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. 847) 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

846
 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

847
AWS IoT API Reference
AwsJobAbortCriteria

848
 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. 850) 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

849
 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. 852) 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

850
 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

851
 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

852
 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

853
 AWS IoT API Reference
Behavior

Behavior
Service: AWS IoT

A Device Defender security profile behavior.

Contents
criteria

The criteria that determine if a device is behaving normally in regard to the metric.

Type: BehaviorCriteria (p. 856) object

Required: No
metric

What is measured by the behavior.

Type: String

Required: No
metricDimension

The dimension for a metric in your behavior. For example, using a TOPIC_FILTER dimension, you
can narrow down the scope of the metric to only MQTT topics where the name matches the pattern
specified in the dimension. This can't be used with custom metrics.

Type: MetricDimension (p. 958) object

Required: No
name

The name you've given to the behavior.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

Required: Yes
suppressAlerts

Suppresses alerts.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2

854
 AWS IoT API Reference
Behavior

• AWS SDK for Ruby V3

855
 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

856
 AWS IoT API Reference
BehaviorCriteria

Type: MachineLearningDetectionConfig (p. 954) 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. 1018) object

Required: No
value

The value to be compared with the metric.

Type: MetricValue (p. 960) 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

857
 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

858
 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

859
 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

860
 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

861
 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

862
 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. 1031) 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

863
 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

864
 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

865
 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. 873) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

866
 AWS IoT API Reference
CACertificateDescription

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

867
 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

868
 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

869
 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.

870
 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

871
 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. 1063) object

Required: No
validity

When the certificate is valid.

Type: CertificateValidity (p. 873) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

872
 AWS IoT API Reference
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

873
 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

874
 AWS IoT API Reference
CloudwatchLogsAction

CloudwatchLogsAction
Service: AWS IoT

Describes an action that sends data to CloudWatch Logs.

Contents
logGroupName

The CloudWatch log group to which the action sends data.

Type: String

Required: Yes
roleArn

The IAM role that allows access to the CloudWatch log.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

875
 AWS IoT API Reference
CloudwatchMetricAction

CloudwatchMetricAction
Service: AWS IoT

Describes an action that captures a CloudWatch metric.

Contents
metricName

The CloudWatch metric name.

Type: String

Required: Yes
metricNamespace

The CloudWatch metric namespace name.

Type: String

Required: Yes
metricTimestamp

An optional Unix timestamp.

Type: String

Required: No
metricUnit

The metric unit supported by CloudWatch.

Type: String

Required: Yes
metricValue

The CloudWatch metric value.

Type: String

Required: Yes
roleArn

The IAM role that allows access to the CloudWatch metric.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2

876
 AWS IoT API Reference
CloudwatchMetricAction

• AWS SDK for Ruby V3

877
 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. 882) object

Required: No
startSigningJobParameter

Describes the code-signing job.

Type: StartSigningJobParameter (p. 1017) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

878
 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

879
 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

880
 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

881
 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. 879) 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. 880) 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

882
 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. 902) 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. 917) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

883
 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. 1003) 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

884
 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.

885
 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

886
 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

887
 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. 962) 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. 890) 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

888
 AWS IoT API Reference
DetectMitigationActionsTaskSummary

Required: No
taskStatistics

The statistics of a mitigation action task.

Type: DetectMitigationActionsTaskStatistics (p. 887) 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. 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

889
 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

890
 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.

891
 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

892
 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

893
 AWS IoT API Reference
DynamoDBAction

DynamoDBAction
Service: AWS IoT

Describes an action to write to a DynamoDB table.

The tableName, hashKeyField, and rangeKeyField values must match the values used when you
created the table.

The hashKeyValue and rangeKeyvalue fields use a substitution template syntax. These templates
provide data at runtime. The syntax is as follows: ${sql-expression}.

You can specify any valid expression in a WHERE or SELECT clause, including JSON properties,
comparisons, calculations, and functions. For example, the following field uses the third level of the
topic:

"hashKeyValue": "${topic(3)}"

The following field uses the timestamp:

"rangeKeyValue": "${timestamp()}"

Contents
hashKeyField

The hash key name.

Type: String

Required: Yes
hashKeyType

The hash key type. Valid values are "STRING" or "NUMBER"

Type: String

Valid Values: STRING | NUMBER

Required: No
hashKeyValue

The hash key value.

Type: String

Required: Yes
operation

The type of operation to be performed. This follows the substitution template, so it can be
${operation}, but the substitution must result in one of the following: INSERT, UPDATE, or
DELETE.

Type: String

Required: No
payloadField

The action payload. This name can be customized.

894
 AWS IoT API Reference
DynamoDBAction

Type: String

Required: No
rangeKeyField

The range key name.

Type: String

Required: No
rangeKeyType

The range key type. Valid values are "STRING" or "NUMBER"

Type: String

Valid Values: STRING | NUMBER

Required: No
rangeKeyValue

The range key value.

Type: String

Required: No
roleArn

The ARN of the IAM role that grants access to the DynamoDB table.

Type: String

Required: Yes
tableName

The name of the DynamoDB table.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

895
 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. 991) 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

896
 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

897
 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

898
 AWS IoT API Reference
ElasticsearchAction

• AWS SDK for Ruby V3

899
 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

900
 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

901
 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. 980) 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

902
 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. 992) 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

903
 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

904
 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. 1004) object

Required: No
stream

The stream that contains the OTA update.

Type: Stream (p. 1022) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

905
 AWS IoT API Reference
FirehoseAction

FirehoseAction
Service: AWS IoT

Describes an action that writes data to an Amazon Kinesis Firehose stream.

Contents
batchMode

Whether to deliver the Kinesis Data Firehose stream as a batch by using PutRecordBatch. The
default value is false.

When batchMode is true and the rule's SQL statement evaluates to an Array, each Array element
forms one record in the PutRecordBatch request. The resulting array can't have more than 500
records.

Type: Boolean

Required: No
deliveryStreamName

The delivery stream name.

Type: String

Required: Yes
roleArn

The IAM role that grants access to the Amazon Kinesis Firehose stream.

Type: String

Required: Yes
separator

A character separator that will be used to separate records written to the Firehose stream. Valid
values are: '\n' (newline), '\t' (tab), '\r\n' (Windows newline), ',' (comma).

Type: String

Pattern: ([\n\t])|(\r\n)|(,)

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

906
 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

907
 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

908
 AWS IoT API Reference
HttpAction

HttpAction
Service: AWS IoT

Send data to an HTTPS endpoint.

Contents
auth

The authentication method to use when sending data to an HTTPS endpoint.

Type: HttpAuthorization (p. 912) 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. 911) objects

Array Members: Minimum number of 0 items. Maximum number of 100 items.

Required: No
url

The endpoint URL. If substitution templates are used in the URL, you must also specify a
confirmationUrl. If this is a new destination, a new TopicRuleDestination is created if
possible.

Type: String

Length Constraints: Maximum length of 2000.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

909
AWS IoT API Reference
HttpAction

910
 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

911
 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. 1014) 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
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

913
 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

914
 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

915
 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

916
 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. 980) 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

917
 AWS IoT API Reference
IndexingFilter

IndexingFilter
Service: AWS IoT

Provides additional filters for specific data sources. Named shadow is the only data source that
currently supports and requires a filter. To add named shadows to your fleet indexing configuration, set
namedShadowIndexingMode to be ON and specify your shadow names in filter.

Contents
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

918
 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

919
 AWS IoT API Reference
IotEventsAction

IotEventsAction
Service: AWS IoT

Sends an input to an AWS IoT Events detector.

Contents
batchMode

Whether to process the event actions as a batch. The default value is false.

When batchMode is true, you can't specify a messageId.

When batchMode is true and the rule SQL statement evaluates to an Array, each Array element is
treated as a separate message when it's sent to AWS IoT Events by calling BatchPutMessage. The
resulting array can't have more than 10 messages.

Type: Boolean

Required: No
inputName

The name of the AWS IoT Events input.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes
messageId

The ID of the message. The default messageId is a new UUID value.

When batchMode is true, you can't specify a messageId--a new UUID value will be assigned.

Assign a value to this property to ensure that only one input (message) with a given messageId will
be processed by an AWS IoT Events detector.

Type: String

Length Constraints: Maximum length of 128.

Required: No
roleArn

The ARN of the role that grants AWS IoT permission to send an input to an AWS IoT Events detector.
("Action":"iotevents:BatchPutMessage").

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

920
 AWS IoT API Reference
IotEventsAction

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

921
 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. 989) 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

922
 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

923
 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. 810) 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
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.

924
 AWS IoT API Reference
Job

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. 931) object

Required: No
jobExecutionsRolloutConfig

Allows you to create a staged rollout of a job.

Type: JobExecutionsRolloutConfig (p. 932) 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.

925
 AWS IoT API Reference
Job

Type: JobProcessDetails (p. 938) 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. 983) object

Required: No
reasonCode

If the job was updated, provides the reason code for the update.

Type: String

Length Constraints: Maximum length of 128.

Pattern: [\p{Upper}\p{Digit}_]+

Required: No
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.

926
 AWS IoT API Reference
Job

Type: SchedulingConfig (p. 1008) 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.

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. 1047) 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

927
 AWS IoT API Reference
Job

• AWS SDK for Java V2

• AWS SDK for Ruby V3

928
 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

929
 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. 933) 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

930
 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. 999) 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

931
 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. 903) 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

932
 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

933
 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:

934
 AWS IoT API Reference
JobExecutionSummary

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

935
 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. 934) 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

936
 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. 934) 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

937
 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

938
 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

939
 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

940
 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

941
 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

942
AWS IoT API Reference
JobTemplateSummary

943
 AWS IoT API Reference
KafkaAction

KafkaAction
Service: AWS IoT

Send messages to an Amazon Managed Streaming for Apache Kafka (Amazon MSK) or self-managed
Apache Kafka cluster.

Contents
clientProperties

Properties of the Apache Kafka producer client.

Type: String to string map

Required: Yes
destinationArn

The ARN of Kafka action's VPC TopicRuleDestination.

Type: String

Required: Yes
key

The Kafka message key.

Type: String

Required: No
partition

The Kafka message partition.

Type: String

Required: No
topic

The Kafka topic for messages to be sent to the Kafka broker.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

944
 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

945
 AWS IoT API Reference
KinesisAction

KinesisAction
Service: AWS IoT

Describes an action to write data to an Amazon Kinesis stream.

Contents
partitionKey

The partition key.

Type: String

Required: No
roleArn

The ARN of the IAM role that grants access to the Amazon Kinesis stream.

Type: String

Required: Yes
streamName

The name of the Amazon Kinesis stream.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

946
 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

947
 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
timestamp

The time that the location data was sampled. The default value is the time the MQTT message was
processed.

Type: LocationTimestamp (p. 950) object

Required: No
trackerName

The name of the tracker resource in Amazon Location in which the location is updated.

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++

948
 AWS IoT API Reference
LocationAction

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

949
 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
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
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

950
 AWS IoT API Reference
LoggingOptionsPayload

LoggingOptionsPayload
Service: AWS IoT

Describes the logging options payload.

Contents
logLevel

The log level.

Type: String

Valid Values: DEBUG | INFO | ERROR | WARN | DISABLED

Required: No
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

951
 AWS IoT API Reference
LogTarget

LogTarget
Service: AWS IoT

A log target.

Contents
targetName

The target name.

Type: String

Required: No
targetType

The target type.

Type: String

Valid Values: DEFAULT | THING_GROUP | CLIENT_ID | SOURCE_IP | PRINCIPAL_ID

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
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. 952) 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
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

954
 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:

955
 AWS IoT API Reference
ManagedJobTemplateSummary

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

956
 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. 960) 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

957
 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

958
 AWS IoT API Reference
MetricToRetain

MetricToRetain
Service: AWS IoT

The metric you want to retain. Dimensions are optional.

Contents
metric

What is measured by the behavior.

Type: String

Required: Yes
metricDimension

The dimension of a metric. This can't be used with custom metrics.

Type: MetricDimension (p. 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

959
 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

960
 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

961
 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. 964) 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

962
 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

963
 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. 819) 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. 900) 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. 988) object

Required: No
replaceDefaultPolicyVersionParams

Parameters to define a mitigation action that adds a blank policy to restrict permissions.

Type: ReplaceDefaultPolicyVersionParams (p. 995) object

Required: No
updateCACertificateParams

Parameters to define a mitigation action that changes the state of the CA certificate to inactive.

Type: UpdateCACertificateParams (p. 1065) object

Required: No
updateDeviceCertificateParams

Parameters to define a mitigation action that changes the state of the device certificate to inactive.

Type: UpdateDeviceCertificateParams (p. 1066) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

964
 AWS IoT API Reference
MitigationActionParams

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

965
 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

966
 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.

967
 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. 1067) 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

968
 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. 997) 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

969
 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

970
 AWS IoT API Reference
OTAUpdateFile

OTAUpdateFile
Service: AWS IoT

Describes a file to be associated with an OTA update.

Contents
attributes

A list of name/attribute pairs.

Type: String to string map

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. 878) object

Required: No
fileLocation

The location of the updated firmware.

Type: FileLocation (p. 905) 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

971
 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

972
 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. 849) object

Required: No
awsJobPresignedUrlConfig

Configuration information for pre-signed URLs. Valid when protocols contains HTTP.

Type: AwsJobPresignedUrlConfig (p. 851) 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

973
 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. 901) 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. 971) 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

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.

974
 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

975
 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

976
 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]+

977
 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

978
 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

979
 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

980
 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

981
 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

982
 AWS IoT API Reference
PresignedUrlConfig

PresignedUrlConfig
Service: AWS IoT

Configuration for pre-signed S3 URLs.

Contents
expiresInSec

How long (in seconds) pre-signed URLs are valid. Valid values are 60 - 3600, the default value is
3600 seconds. Pre-signed URLs are generated when Jobs receives an MQTT request for the job
document.

Type: Long

Valid Range: Minimum value of 60. Maximum value of 3600.

Required: No
roleArn

The ARN of an IAM role that grants grants permission to download files from the S3 bucket where
the job data/updates are stored. The role must also grant permission for IoT to download the files.
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

983
 AWS IoT API Reference
ProvisioningHook

ProvisioningHook
Service: AWS IoT

Structure that contains payloadVersion and targetArn.

Contents
payloadVersion

The payload that was sent to the target function.

Note: Only Lambda functions are currently supported.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 32.

Pattern: ^[0-9-]+$

Required: No
targetArn

The ARN of the target function.

Note: Only Lambda functions are currently supported.

Type: String

Length Constraints: Maximum length of 2048.

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

984
 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

985
 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

986
 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

987
 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

988
 AWS IoT API Reference
PutAssetPropertyValueEntry

PutAssetPropertyValueEntry
Service: AWS IoT

An asset property value entry containing the following information.

Contents
assetId

The ID of the AWS IoT SiteWise asset. You must specify either a propertyAlias or both an
aliasId and a propertyId. Accepts substitution templates.

Type: String

Required: No
entryId

Optional. A unique identifier for this entry that you can define to better track which message caused
an error in case of failure. Accepts substitution templates. Defaults to a new UUID.

Type: String

Required: No
propertyAlias

The name of the property alias associated with your asset property. You must specify either a
propertyAlias or both an aliasId and a propertyId. Accepts substitution templates.

Type: String

Length Constraints: Minimum length of 1.

Required: No
propertyId

The ID of the asset's property. You must specify either a propertyAlias or both an aliasId and a
propertyId. Accepts substitution templates.

Type: String

Required: No
propertyValues

A list of property values to insert that each contain timestamp, quality, and value (TQV) information.

Type: Array of AssetPropertyValue (p. 824) 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

989
 AWS IoT API Reference
PutAssetPropertyValueEntry

• AWS SDK for Java V2

• AWS SDK for Ruby V3

990
 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

991
 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

992
 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

993
 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. 997) 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

994
 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

995
 AWS IoT API Reference
RepublishAction

RepublishAction
Service: AWS IoT

Describes an action to republish to another topic.

Contents
headers

MQTT Version 5.0 headers information. For more information, see MQTT from the AWS IoT Core
Developer Guide.

Type: MqttHeaders (p. 967) 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
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes
topic

The name of the MQTT topic.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

996
 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]+

997
 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. 923) object

Required: No
policyVersionIdentifier

The version of the policy associated with the resource.

Type: PolicyVersionIdentifier (p. 982) 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

998
 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

999
 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.

1000
 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

1001
 AWS IoT API Reference
S3Action

S3Action
Service: AWS IoT

Describes an action to write data to an Amazon S3 bucket.

Contents
bucketName

The Amazon S3 bucket.

Type: String

Required: Yes
cannedAcl

The Amazon S3 canned ACL that controls access to the object identified by the object key. For more
information, see S3 canned ACLs.

Type: String

Valid Values: private | public-read | public-read-write | aws-exec-read |

authenticated-read | bucket-owner-read | bucket-owner-full-control | log-
delivery-write

Required: No
key

The object key. For more information, see Actions, resources, and condition keys for Amazon S3.

Type: String

Required: Yes
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1002
 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

1003
 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

1004
 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

1005
 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:

1006
 AWS IoT API Reference
ScheduledAuditMetadata

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1007
 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.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

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.

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

1008
 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

1009
 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

1010
 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. 1009) object

Required: No
target

Information about the target (thing group) associated with the security profile.

Type: SecurityProfileTarget (p. 1010) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1011
 AWS IoT API Reference
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

1012
 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

1013
 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

1014
 AWS IoT API Reference
SnsAction

SnsAction
Service: AWS IoT

Describes an action to publish to an Amazon SNS topic.

Contents
messageFormat

(Optional) The message format of the message to publish. Accepted values are "JSON" and "RAW".
The default value of the attribute is "RAW". SNS uses this setting to determine if the payload should
be parsed and relevant platform-specific bits of the payload should be extracted. To read more
about SNS message formats, see https://docs.aws.amazon.com/sns/latest/dg/json-formats.html
refer to their official documentation.

Type: String

Valid Values: RAW | JSON

Required: No
roleArn

The ARN of the IAM role that grants access.

Type: String

Required: Yes
targetArn

The ARN of the SNS topic.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1015
 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

1016
 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. 884) object

Required: No
signingProfileName

The code-signing profile name.

Type: String

Required: No
signingProfileParameter

Describes the code-signing profile.

Type: SigningProfileParameter (p. 1013) 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

1017
 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

1018
 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

1019
 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

1020
 AWS IoT API Reference
StepFunctionsAction

StepFunctionsAction
Service: AWS IoT

Starts execution of a Step Functions state machine.

Contents
executionNamePrefix

(Optional) A name will be given to the state machine execution consisting of this prefix followed by a
UUID. Step Functions automatically creates a unique name for each state machine execution if one is
not provided.

Type: String

Required: No
roleArn

The ARN of the role that grants IoT permission to start execution of a state machine
("Action":"states:StartExecution").

Type: String

Required: Yes
stateMachineName

The name of the Step Functions state machine whose execution will be started.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1021
 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

1022
 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. 1004) 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

1023
 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. 1023) 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.

1024
 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

1025
 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

1026
 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

1027
 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

1028
 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

1029
 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

1030
 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

1031
 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

1032
 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

1033
 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

1034
 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. 1034) 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

1035
 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

1036
 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

1037
 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

1038
 AWS IoT API Reference
ThingGroupIndexingConfiguration

ThingGroupIndexingConfiguration
Service: AWS IoT

Thing group indexing configuration.

Contents
customFields

A list of thing group fields to index. This list cannot contain any managed fields. Use the
GetIndexingConfiguration API to get a list of managed fields.

Contains custom field names and their data type.

Type: Array of Field (p. 904) 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.

Type: Array of Field (p. 904) objects

Required: No
thingGroupIndexingMode

Thing group indexing mode.

Type: String

Valid Values: OFF | ON

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1039
 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. 908) 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

1040
 AWS IoT API Reference
ThingGroupProperties

ThingGroupProperties
Service: AWS IoT

Thing group properties.

Contents
attributePayload

The thing group attributes in JSON format.

Type: AttributePayload (p. 826) 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

1041
 AWS IoT API Reference
ThingIndexingConfiguration

ThingIndexingConfiguration
Service: AWS IoT

The thing indexing configuration. For more information, see Managing Thing Indexing.

Contents
customFields

Contains custom field names and their data type.

Type: Array of Field (p. 904) 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 filters for specific data sources. Named shadow is the only data source that
currently supports and requires a filter. To add named shadows to your fleet indexing configuration,
set namedShadowIndexingMode to be ON and specify your shadow names in filter.

Type: IndexingFilter (p. 918) object

Required: No
managedFields

Contains fields that are indexed and whose types are already known by the Fleet Indexing service.

Type: Array of Field (p. 904) 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

1042
 AWS IoT API Reference
ThingIndexingConfiguration

thingConnectivityIndexingMode

Thing connectivity indexing mode. Valid values are:

• STATUS – Your thing index contains connectivity status. To enable thing connectivity indexing,
thingIndexMode must not be set to OFF.
• OFF - Thing connectivity status indexing is disabled.

Type: String

Valid Values: OFF | STATUS

Required: No
thingIndexingMode

Thing indexing mode. Valid values are:

• REGISTRY – Your thing index contains registry data only.
• REGISTRY_AND_SHADOW - Your thing index contains registry and shadow data.
• OFF - Thing indexing is disabled.

Type: String

Valid Values: OFF | REGISTRY | REGISTRY_AND_SHADOW

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1043
 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. 1045) 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. 1046) 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

1044
 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

1045
 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

1046
 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

1047
 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. 1050) 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. 1051) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

1048
 AWS IoT API Reference
TimestreamAction

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1049
 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

1050
 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

1051
 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

1052
 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. 813) 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. 813) 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.

1053
 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

1054
 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. 915) 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

1055
 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. 1074) 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

1056
 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. 914) object

Required: No
vpcConfiguration

Configuration of the virtual private cloud (VPC) connection.

Type: VpcDestinationConfiguration (p. 1073) 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

1057
 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. 916) 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

1058
 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. 1075) 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

1059
 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

1060
 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. 813) objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: Yes
awsIotSqlVersion

The version of the SQL rules engine to use when evaluating the rule.

Type: String

Required: No
description

The description of the rule.

Type: String

Required: No
errorAction

The action to take when an error occurs.

Type: Action (p. 813) object

Required: No
ruleDisabled

Specifies whether the rule is disabled.

Type: Boolean

Required: No
sql

The SQL statement used to query the topic. For more information, see AWS IoT SQL Reference in the
AWS IoT Developer Guide.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

1061
 AWS IoT API Reference
TopicRulePayload

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1062
 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

1063
 AWS IoT API Reference
TransferData

• AWS SDK for Java V2

• AWS SDK for Ruby V3

1064
 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

1065
 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

1066
 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

1067
 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

1068
 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. 854) object

Required: No
metricValue

The value of the metric (the measurement).

Type: MetricValue (p. 960) 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}]*

1069
 AWS IoT API Reference
ViolationEvent

Required: No
violationEventAdditionalInfo

The details of a violation event.

Type: ViolationEventAdditionalInfo (p. 1071) 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

1070
 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

1071
 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

1072
 AWS IoT API Reference
VpcDestinationConfiguration

VpcDestinationConfiguration
Service: AWS IoT

The configuration information for a virtual private cloud (VPC) destination.

Contents
roleArn

The ARN of a role that has permission to create and attach to elastic network interfaces (ENIs).

Type: String

Required: Yes
securityGroups

The security groups of the VPC destination.

Type: Array of strings

Required: No
subnetIds

The subnet IDs of the VPC destination.

Type: Array of strings

Required: Yes
vpcId

The ID of the VPC.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1073
 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

1074
 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. 1076)

1075
 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. 1078)

• JobExecutionState (p. 1081)
• JobExecutionSummary (p. 1082)

1076
AWS IoT API Reference
AWS IoT jobs data

1077
 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

1078
 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++

1079
 AWS IoT API Reference
JobExecution

• AWS SDK for Go

• AWS SDK for Java V2
• AWS SDK for Ruby V3

1080
 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

1081
 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:

1082
 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. 1084)

• GroupResult (p. 1085)
• SuiteDefinitionConfiguration (p. 1086)
• SuiteDefinitionInformation (p. 1088)
• SuiteRunConfiguration (p. 1090)
• SuiteRunInformation (p. 1091)
• TestCaseRun (p. 1093)
• TestResult (p. 1095)

1083
 AWS IoT API Reference
DeviceUnderTest

DeviceUnderTest
Service: AWS IoT Core Device Advisor

Information of a test device. A thing ARN or a certificate ARN is required.

Contents
certificateArn

Lists devices certificate ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
thingArn

Lists devices thing ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1084
 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. 1093) 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

1085
 AWS IoT API Reference
SuiteDefinitionConfiguration

SuiteDefinitionConfiguration
Service: AWS IoT Core Device Advisor

Gets Suite Definition Configuration.

Contents
devicePermissionRoleArn

Gets the device permission ARN.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
devices

Gets the devices configured.

Type: Array of DeviceUnderTest (p. 1084) objects

Array Members: Minimum number of 0 items. Maximum number of 2 items.

Required: No
intendedForQualification

Gets the tests intended for qualification in a suite.

Type: Boolean

Required: No
rootGroup

Gets test suite root group.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
suiteDefinitionName

Gets Suite Definition Configuration name.

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

1086
 AWS IoT API Reference
SuiteDefinitionConfiguration

• AWS SDK for Java V2

• AWS SDK for Ruby V3

1087
 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. 1084) objects

Array Members: Minimum number of 0 items. Maximum number of 2 items.

Required: No
intendedForQualification

Specifies if the test suite is intended for qualification.

Type: Boolean

Required: No
suiteDefinitionId

Suite definition ID of the test suite.

Type: String

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No
suiteDefinitionName

Suite name of the test suite.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1088
 AWS IoT API Reference
SuiteDefinitionInformation

1089
 AWS IoT API Reference
SuiteRunConfiguration

SuiteRunConfiguration
Service: AWS IoT Core Device Advisor

Gets suite run configuration.

Contents
parallelRun

TRUE if multiple test suites run in parallel.

Type: Boolean

Required: No
primaryDevice

Gets the primary device for suite run.

Type: DeviceUnderTest (p. 1084) object

Required: No
selectedTestList

Gets test case list.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 100 items.

Length Constraints: Minimum length of 12. Maximum length of 36.

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

1090
 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

1091
 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

1092
 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.

1093
 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
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

1094
 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. 1085) 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. 1096)

1095
 AWS IoT API Reference
ApplicationSummary

ApplicationSummary
Service: AWS IoT Fleet Hub

A summary of information about a Fleet Hub for AWS IoT Device Management web application.

Contents
applicationCreationDate

The date (in Unix epoch time) when the web application was created.

Type: Long

Required: No
applicationDescription

An optional description of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^[ -~]*$

Required: No
applicationId

The unique Id of the web application.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Required: Yes
applicationLastUpdateDate

The date (in Unix epoch time) when the web application was last updated.

Type: Long

Required: No
applicationName

The name of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: ^[ -~]*$

Required: Yes
applicationState

The current state of the web application.

Type: String

1096
 AWS IoT API Reference
AWS IoT Secure Tunneling

Valid Values: CREATING | DELETING | ACTIVE | CREATE_FAILED | DELETE_FAILED

Required: No
applicationUrl

The URL of the web application.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: ^https\://\S+$

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3

AWS IoT Secure Tunneling

The following data types are supported by AWS IoT Secure Tunneling:

• ConnectionState (p. 1098)

• DestinationConfig (p. 1099)
• Tag (p. 1100)
• TimeoutConfig (p. 1101)
• Tunnel (p. 1102)
• TunnelSummary (p. 1104)

1097
 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

1098
 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

1099
 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

1100
 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

1101
 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. 1099) object

Required: No
destinationConnectionState

The connection state of the destination application.

Type: ConnectionState (p. 1098) 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. 1098) object

Required: No
status

The status of a tunnel. Valid values are: Open and Closed.

Type: String

Valid Values: OPEN | CLOSED

1102
 AWS IoT API Reference
Tunnel

Required: No
tags

A list of tag metadata associated with the secure tunnel.

Type: Array of Tag (p. 1100) objects

Array Members: Minimum number of 1 item. Maximum number of 200 items.

Required: No
timeoutConfig

Timeout configuration for the tunnel.

Type: TimeoutConfig (p. 1101) 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

1103
 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

1104
 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

1105
 AWS IoT API Reference

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is

1106
 AWS IoT API Reference

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional

1107