AWS Step Functions
API Reference (API Version 2016-11-23)
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

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.

Note

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

Note

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 and definition. 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", "name": "string", "roleArn": "string", "tags": [ { "key": "string", "value": "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. See Amazon States Language.

Type: String

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

Required: Yes

name

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)

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

tags

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

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

TooManyTags

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

HTTP Status Code: 400

See Also

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