CreateStateMachine - Amazon Step Functions
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 state machine. A state machine consists of a collection of states that can do work (Task states), determine to which states to transition next (Choice states), stop an execution with an error (Fail states), and so on. State machines are specified using a JSON-based, structured language. For more information, see Amazon States Language in the Amazon Step Functions User Guide.

If you set the publish parameter of this API action to true, it publishes version 1 as the first revision of the state machine.


This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.


CreateStateMachine is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateStateMachine's idempotency check is based on the state machine name, definition, type, LoggingConfiguration, and TracingConfiguration. The check is also based on the publish and versionDescription parameters. If a following request has a different roleArn or tags, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, roleArn and tags will not be updated, even if they are different.

Request Syntax

{ "definition": "string", "loggingConfiguration": { "destinations": [ { "cloudWatchLogsLogGroup": { "logGroupArn": "string" } } ], "includeExecutionData": boolean, "level": "string" }, "name": "string", "publish": boolean, "roleArn": "string", "tags": [ { "key": "string", "value": "string" } ], "tracingConfiguration": { "enabled": boolean }, "type": "string", "versionDescription": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.


The Amazon States Language definition of the state machine. See Amazon States Language.

Type: String

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

Required: Yes


Defines what execution history events are logged and where they are logged.


By default, the level is set to OFF. For more information see Log Levels in the Amazon Step Functions User Guide.

Type: LoggingConfiguration object

Required: No


The name of the state machine.

A name must not contain:

  • white space

  • brackets < > { } [ ]

  • wildcard characters ? *

  • special characters " # % \ ^ | ~ ` $ & , ; : /

  • control characters (U+0000-001F, U+007F-009F)

To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.

Type: String

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

Required: Yes


Set to true to publish the first version of the state machine during creation. The default is false.

Type: Boolean

Required: No


The Amazon Resource Name (ARN) of the IAM role to use for this state machine.

Type: String

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

Required: Yes


Tags to be added when creating a state machine.

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Billing and Cost Management User Guide, and Controlling Access Using IAM Tags.

Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.

Type: Array of Tag objects

Required: No


Selects whether Amazon X-Ray tracing is enabled.

Type: TracingConfiguration object

Required: No


Determines whether a Standard or Express state machine is created. The default is STANDARD. You cannot update the type of a state machine once it has been created.

Type: String


Required: No


Sets description about the state machine version. You can only set the description if the publish parameter is set to true. Otherwise, if you set versionDescription, but publish to false, this API action throws ValidationException.

Type: String

Length Constraints: Maximum length of 256.

Required: No

Response Syntax

{ "creationDate": number, "stateMachineArn": "string", "stateMachineVersionArn": "string" }

Response Elements

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

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


The date the state machine is created.

Type: Timestamp


The Amazon Resource Name (ARN) that identifies the created state machine.

Type: String

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


The Amazon Resource Name (ARN) that identifies the created state machine version. If you do not set the publish parameter to true, this field returns null value.

Type: String

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


For information about the errors that are common to all actions, see Common Errors.


Updating or deleting a resource can cause an inconsistent state. This error occurs when there're concurrent requests for DeleteStateMachineVersion, PublishStateMachineVersion, or UpdateStateMachine with the publish parameter set to true.

HTTP Status Code: 409

HTTP Status Code: 400


The provided Amazon Resource Name (ARN) is not valid.

HTTP Status Code: 400


The provided Amazon States Language definition is not valid.

HTTP Status Code: 400


HTTP Status Code: 400


The provided name is not valid.

HTTP Status Code: 400


Your tracingConfiguration key does not match, or enabled has not been set to true or false.

HTTP Status Code: 400


A state machine with the same name but a different definition or role ARN already exists.

HTTP Status Code: 400


The specified state machine is being deleted.

HTTP Status Code: 400


The maximum number of state machines has been reached. Existing state machines must be deleted before a new state machine can be created.

HTTP Status Code: 400


HTTP Status Code: 400


You've exceeded the number of tags allowed for a resource. See the Limits Topic in the Amazon Step Functions Developer Guide.

HTTP Status Code: 400


The input does not satisfy the constraints specified by an Amazon service.

HTTP Status Code: 400

See Also

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