AWS Step Functions
Developer Guide

Creating a Step Functions API Using API Gateway

You can use Amazon API Gateway to associate your AWS Step Functions APIs with methods in an API Gateway API. When an HTTPS request is sent to an API method, API Gateway invokes your Step Functions API actions.

This tutorial shows you how to create an API that uses one resource and the POST method to communicate with the StartExecution API action. You'll use the IAM console to create a role for API Gateway. Then, you'll use the API Gateway console to create an API Gateway API, create a resource and method, and map the method to the StartExecution API action. Finally, you'll deploy and test your API. For more information about this API action, see StartExecution in the AWS Step Functions API Reference.


While Amazon API Gateway can start a Step Functions execution by calling StartExecution you must call DescribeExecution to get the result.

Step 1: Creating an IAM Role for API Gateway

Before you create your API Gateway API, you need to give API Gateway permission to call Step Functions API actions.

To create a role for API Gateway

  1. Log in to the IAM console and choose Roles, Create role.

  2. On the Select type of trusted entity page, under AWS service, select API Gateway from the list and then choose Next: Permissions.

  3. On the Attached permissions policy page, choose Next: Review.

  4. On the Review page, type APIGatewayToStepFunctions for Role name and then choose Create role.

    The IAM role appears in the list of roles.

  5. Choose the name of your role and note the Role ARN, for example:


To attach a policy to the IAM role

  1. On the Roles page, search for your role (APIGatewayToStepFunctions) and then choose the role.

  2. On the Permissions tab, choose Attach Policy.

  3. On the Attach Policy page, search for AWSStepFunctionsFullAccess, choose the policy, and then choose Attach Policy.

Step 2: Creating your API Gateway API

After you create your IAM role, you can create your custom API Gateway API.

To create the API

  1. Navigate to the Amazon API Gateway console and choose Get Started.

  2. On the Create new API page, choose New API.

  3. In the Settings section, type StartExecutionAPI for the API name, and then choose Create API.

To create a resource

  1. On the Resources page of StartExecutionAPI, choose Actions, Create Resource.

  2. On the New Child Resource page, type execution for Resource Name, and then choose Create Resource.

To create a POST Method

  1. On the /execution Methods page, choose Actions, Create Method.

  2. From the list, choose POST, and then select the checkmark.

To configure the method

On the /execution - POST - Setup page, configure the integration point for your method.

  1. For Integration Type, choose AWS Service.

  2. For AWS Region, choose a region from the list.


    For regions that currently support Step Functions, see the Supported Regions.

  3. For AWS Service, choose Step Functions from the list.

  4. For HTTP Method, choose POST from the list.


    All Step Functions API actions use the HTTP POST method.

  5. For Action Type, choose Use action name.

  6. For Action, type StartExecution.

  7. For Execution Role, type the role ARN of the IAM role that you created earlier, for example:

  8. Choose Save.

    The visual mapping between API Gateway and Step Functions is displayed on the /execution - POST - Method Execution page.

Step 3: Testing and Deploying the API Gateway API

To test the communication between API Gateway and Step Functions

  1. On the /execution - POST - Method Execution page, choose Test.

  2. On the /execution - POST - Method Test page, copy the following request parameters into the Request Body section using the ARN of an existing state machine (or create a new state machine), and then choose Test.

    { "input": "{}", "name": "MyExecution", "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld" }


    For more information, see the StartExecution Request Syntax in the AWS Step Functions API Reference.

    If you don't want to include the ARN of your state machine in the body of your API Gateway call, you can configure a body-mapping template, for example:

    { "input": "$util.escapeJavaScript($input.json('$'))", "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld" }

    This approach allows you to have different state machines based on your development stages (for example, dev, test, and prod). To release an update, you only need to change the stage variable, for example:

    { "input": "$util.escapeJavaScript($input.json('$'))", "stateMachineArn": "$util.escapeJavaScript($stageVariables.get(arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld))" }
  3. The execution starts and the execution ARN and its epoch date are displayed under Response Body.

    { "executionArn": "arn:aws:states:us-east-1:123456789012:execution:HelloWorld:MyExecution", "startDate": 1486768956.878 }


    You can view the execution by choosing your state machine on the AWS Step Functions console.

To deploy your API

  1. On the Resources page of StartExecutionAPI, choose Actions, Deploy API.

  2. In the Deploy API dialog box, select [New Stage] from the Deployment stage list, type alpha for Stage name, and then choose Deploy.

To test your deployment

  1. On the Stages page of StartExecutionAPI, expand alpha, /, /execution, POST.

  2. On the alpha - POST - /execution page, note the Invoke URL, for example:
  3. From the command line, run the curl command using the ARN of your state machine, and then invoke the URL of your deployment, for example:

    curl -X POST -d '{"input": "{}","name": "MyExecution","stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld"}'

    The execution ARN and its epoch date are returned, for example: