Menu
AWS Step Functions
API Reference (API Version 2016-11-23)

CreateStateMachine

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.

Request Syntax

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

definition

The Amazon States Language definition of the state machine.

Type: String

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

Required: Yes

name

The name of the state machine. This name must be unique for your AWS account and region for 90 days. For more information, see Limits Related to State Machine Executions in the AWS Step Functions Developer Guide.

A name must not contain:

  • whitespace

  • brackets < > { } [ ]

  • wildcard characters ? *

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

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

Type: String

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

Required: Yes

roleArn

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

Response Syntax

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

Response Elements

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

The date the state machine is created.

Type: Timestamp

stateMachineArn

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

Type: String

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

Errors

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

InvalidArn

The provided Amazon Resource Name (ARN) is invalid.

HTTP Status Code: 400

InvalidDefinition

The provided Amazon States Language definition is invalid.

HTTP Status Code: 400

InvalidName

The provided name is invalid.

HTTP Status Code: 400

StateMachineAlreadyExists

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

HTTP Status Code: 400

StateMachineDeleting

The specified state machine is being deleted.

HTTP Status Code: 400

StateMachineLimitExceeded

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

See Also

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