CreateTopicRule - Amazon IoT
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).


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

Requires permission to access the CreateTopicRule action.

Request Syntax

POST /rules/ruleName HTTP/1.1 x-amz-tagging: tags Content-type: application/json { "actions": [ { "cloudwatchAlarm": { "alarmName": "string", "roleArn": "string", "stateReason": "string", "stateValue": "string" }, "cloudwatchLogs": { "batchMode": boolean, "logGroupName": "string", "roleArn": "string" }, "cloudwatchMetric": { "metricName": "string", "metricNamespace": "string", "metricTimestamp": "string", "metricUnit": "string", "metricValue": "string", "roleArn": "string" }, "dynamoDB": { "hashKeyField": "string", "hashKeyType": "string", "hashKeyValue": "string", "operation": "string", "payloadField": "string", "rangeKeyField": "string", "rangeKeyType": "string", "rangeKeyValue": "string", "roleArn": "string", "tableName": "string" }, "dynamoDBv2": { "putItem": { "tableName": "string" }, "roleArn": "string" }, "elasticsearch": { "endpoint": "string", "id": "string", "index": "string", "roleArn": "string", "type": "string" }, "firehose": { "batchMode": boolean, "deliveryStreamName": "string", "roleArn": "string", "separator": "string" }, "http": { "auth": { "sigv4": { "roleArn": "string", "serviceName": "string", "signingRegion": "string" } }, "confirmationUrl": "string", "headers": [ { "key": "string", "value": "string" } ], "url": "string" }, "iotAnalytics": { "batchMode": boolean, "channelArn": "string", "channelName": "string", "roleArn": "string" }, "iotEvents": { "batchMode": boolean, "inputName": "string", "messageId": "string", "roleArn": "string" }, "iotSiteWise": { "putAssetPropertyValueEntries": [ { "assetId": "string", "entryId": "string", "propertyAlias": "string", "propertyId": "string", "propertyValues": [ { "quality": "string", "timestamp": { "offsetInNanos": "string", "timeInSeconds": "string" }, "value": { "booleanValue": "string", "doubleValue": "string", "integerValue": "string", "stringValue": "string" } } ] } ], "roleArn": "string" }, "kafka": { "clientProperties": { "string" : "string" }, "destinationArn": "string", "headers": [ { "key": "string", "value": "string" } ], "key": "string", "partition": "string", "topic": "string" }, "kinesis": { "partitionKey": "string", "roleArn": "string", "streamName": "string" }, "lambda": { "functionArn": "string" }, "location": { "deviceId": "string", "latitude": "string", "longitude": "string", "roleArn": "string", "timestamp": { "unit": "string", "value": "string" }, "trackerName": "string" }, "openSearch": { "endpoint": "string", "id": "string", "index": "string", "roleArn": "string", "type": "string" }, "republish": { "headers": { "contentType": "string", "correlationData": "string", "messageExpiry": "string", "payloadFormatIndicator": "string", "responseTopic": "string", "userProperties": [ { "key": "string", "value": "string" } ] }, "qos": number, "roleArn": "string", "topic": "string" }, "s3": { "bucketName": "string", "cannedAcl": "string", "key": "string", "roleArn": "string" }, "salesforce": { "token": "string", "url": "string" }, "sns": { "messageFormat": "string", "roleArn": "string", "targetArn": "string" }, "sqs": { "queueUrl": "string", "roleArn": "string", "useBase64": boolean }, "stepFunctions": { "executionNamePrefix": "string", "roleArn": "string", "stateMachineName": "string" }, "timestream": { "databaseName": "string", "dimensions": [ { "name": "string", "value": "string" } ], "roleArn": "string", "tableName": "string", "timestamp": { "unit": "string", "value": "string" } } } ], "awsIotSqlVersion": "string", "description": "string", "errorAction": { "cloudwatchAlarm": { "alarmName": "string", "roleArn": "string", "stateReason": "string", "stateValue": "string" }, "cloudwatchLogs": { "batchMode": boolean, "logGroupName": "string", "roleArn": "string" }, "cloudwatchMetric": { "metricName": "string", "metricNamespace": "string", "metricTimestamp": "string", "metricUnit": "string", "metricValue": "string", "roleArn": "string" }, "dynamoDB": { "hashKeyField": "string", "hashKeyType": "string", "hashKeyValue": "string", "operation": "string", "payloadField": "string", "rangeKeyField": "string", "rangeKeyType": "string", "rangeKeyValue": "string", "roleArn": "string", "tableName": "string" }, "dynamoDBv2": { "putItem": { "tableName": "string" }, "roleArn": "string" }, "elasticsearch": { "endpoint": "string", "id": "string", "index": "string", "roleArn": "string", "type": "string" }, "firehose": { "batchMode": boolean, "deliveryStreamName": "string", "roleArn": "string", "separator": "string" }, "http": { "auth": { "sigv4": { "roleArn": "string", "serviceName": "string", "signingRegion": "string" } }, "confirmationUrl": "string", "headers": [ { "key": "string", "value": "string" } ], "url": "string" }, "iotAnalytics": { "batchMode": boolean, "channelArn": "string", "channelName": "string", "roleArn": "string" }, "iotEvents": { "batchMode": boolean, "inputName": "string", "messageId": "string", "roleArn": "string" }, "iotSiteWise": { "putAssetPropertyValueEntries": [ { "assetId": "string", "entryId": "string", "propertyAlias": "string", "propertyId": "string", "propertyValues": [ { "quality": "string", "timestamp": { "offsetInNanos": "string", "timeInSeconds": "string" }, "value": { "booleanValue": "string", "doubleValue": "string", "integerValue": "string", "stringValue": "string" } } ] } ], "roleArn": "string" }, "kafka": { "clientProperties": { "string" : "string" }, "destinationArn": "string", "headers": [ { "key": "string", "value": "string" } ], "key": "string", "partition": "string", "topic": "string" }, "kinesis": { "partitionKey": "string", "roleArn": "string", "streamName": "string" }, "lambda": { "functionArn": "string" }, "location": { "deviceId": "string", "latitude": "string", "longitude": "string", "roleArn": "string", "timestamp": { "unit": "string", "value": "string" }, "trackerName": "string" }, "openSearch": { "endpoint": "string", "id": "string", "index": "string", "roleArn": "string", "type": "string" }, "republish": { "headers": { "contentType": "string", "correlationData": "string", "messageExpiry": "string", "payloadFormatIndicator": "string", "responseTopic": "string", "userProperties": [ { "key": "string", "value": "string" } ] }, "qos": number, "roleArn": "string", "topic": "string" }, "s3": { "bucketName": "string", "cannedAcl": "string", "key": "string", "roleArn": "string" }, "salesforce": { "token": "string", "url": "string" }, "sns": { "messageFormat": "string", "roleArn": "string", "targetArn": "string" }, "sqs": { "queueUrl": "string", "roleArn": "string", "useBase64": boolean }, "stepFunctions": { "executionNamePrefix": "string", "roleArn": "string", "stateMachineName": "string" }, "timestream": { "databaseName": "string", "dimensions": [ { "name": "string", "value": "string" } ], "roleArn": "string", "tableName": "string", "timestamp": { "unit": "string", "value": "string" } } }, "ruleDisabled": boolean, "sql": "string" }

URI Request Parameters

The request uses the following URI parameters.


The name of the rule.

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

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

Required: Yes


Metadata which can be used to manage the topic rule.


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.


The actions associated with the rule.

Type: Array of Action objects

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

Required: Yes


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

Type: String

Required: No


The description of the rule.

Type: String

Required: No


The action to take when an error occurs.

Type: Action object

Required: No


Specifies whether the rule is disabled.

Type: Boolean

Required: No


The SQL statement used to query the topic. For more information, see Amazon IoT SQL Reference in the Amazon IoT Developer Guide.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

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



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

HTTP Status Code: 409


An unexpected error has occurred.

HTTP Status Code: 500


The request is not valid.

HTTP Status Code: 400


The resource already exists.

HTTP Status Code: 409


The service is temporarily unavailable.

HTTP Status Code: 503


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 Amazon SDKs, see the following: