Amazon Step Functions State Machines API

openapi: 3.1.0
info:
  title: Amazon Step Functions Executions State Machines API
  description: Amazon Step Functions is a serverless workflow orchestration service that lets you coordinate distributed applications and microservices using visual workflows. This API enables you to create and manage state machines, start and monitor executions, and retrieve execution history.
  version: '2016-11-23'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
servers:
- url: https://states.{region}.amazonaws.com
  description: Amazon Step Functions Regional Endpoint
  variables:
    region:
      default: us-east-1
      description: AWS Region
security:
- sigv4Auth: []
tags:
- name: State Machines
  description: Operations for creating, updating, describing, and deleting state machines
paths:
  /#X-Amz-Target=AWSStepFunctions.CreateStateMachine:
    post:
      operationId: createStateMachine
      summary: Amazon Step Functions Create a state machine
      description: Creates a state machine. A state machine consists of a collection of states that can do work (Task states), make choices (Choice states), and stop an execution with a success or failure (Succeed or Fail states).
      tags:
      - State Machines
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target-CreateStateMachine'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/CreateStateMachineInput'
      responses:
        '200':
          description: Successfully created state machine
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/CreateStateMachineOutput'
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
        '403':
          description: Authorization failure
        '409':
          description: State machine already exists
  /#X-Amz-Target=AWSStepFunctions.DescribeStateMachine:
    post:
      operationId: describeStateMachine
      summary: Amazon Step Functions Describe a state machine
      description: Provides information about a state machine's definition, its IAM role ARN, and configuration. A qualified state machine ARN can refer to a specific version or alias.
      tags:
      - State Machines
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target-DescribeStateMachine'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              type: object
              required:
              - stateMachineArn
              properties:
                stateMachineArn:
                  type: string
                  description: The ARN of the state machine to describe
      responses:
        '200':
          description: Successfully described state machine
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/DescribeStateMachineOutput'
        '400':
          description: Invalid request parameters
        '404':
          description: State machine does not exist
  /#X-Amz-Target=AWSStepFunctions.ListStateMachines:
    post:
      operationId: listStateMachines
      summary: Amazon Step Functions List state machines
      description: Lists the existing state machines. Returns a paginated list of state machine ARNs, names, types, and creation dates.
      tags:
      - State Machines
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target-ListStateMachines'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              type: object
              properties:
                maxResults:
                  type: integer
                  minimum: 0
                  maximum: 1000
                  description: The maximum number of results to return
                nextToken:
                  type: string
                  description: Pagination token from a previous call
      responses:
        '200':
          description: Successfully listed state machines
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/ListStateMachinesOutput'
        '400':
          description: Invalid request parameters
  /#X-Amz-Target=AWSStepFunctions.UpdateStateMachine:
    post:
      operationId: updateStateMachine
      summary: Amazon Step Functions Update a state machine
      description: Updates an existing state machine by modifying its definition, roleArn, loggingConfiguration, or tracingConfiguration. Running executions will continue to use the previous definition and role ARN.
      tags:
      - State Machines
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target-UpdateStateMachine'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/UpdateStateMachineInput'
      responses:
        '200':
          description: Successfully updated state machine
          content:
            application/x-amz-json-1.0:
              schema:
                type: object
                properties:
                  updateDate:
                    type: string
                    format: date-time
                    description: The date the state machine was updated
        '400':
          description: Invalid request parameters
        '404':
          description: State machine does not exist
  /#X-Amz-Target=AWSStepFunctions.DeleteStateMachine:
    post:
      operationId: deleteStateMachine
      summary: Amazon Step Functions Delete a state machine
      description: Deletes a state machine. This is an asynchronous operation. It sets the state machine status to DELETING and begins the deletion process. A qualified state machine ARN can refer to a specific version.
      tags:
      - State Machines
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target-DeleteStateMachine'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              type: object
              required:
              - stateMachineArn
              properties:
                stateMachineArn:
                  type: string
                  description: The ARN of the state machine to delete
      responses:
        '200':
          description: Successfully initiated state machine deletion
        '400':
          description: Invalid request parameters
components:
  schemas:
    LoggingConfiguration:
      type: object
      description: Logging configuration for a state machine
      properties:
        level:
          type: string
          description: Defines which category of execution history events are logged
          enum:
          - ALL
          - ERROR
          - FATAL
          - 'OFF'
        includeExecutionData:
          type: boolean
          description: Determines whether execution data is included in log messages
        destinations:
          type: array
          description: Array of log destination objects
          items:
            type: object
            properties:
              cloudWatchLogsLogGroup:
                type: object
                properties:
                  logGroupArn:
                    type: string
                    description: The ARN of the CloudWatch log group
    Tag:
      type: object
      description: Describes a resource tag
      properties:
        key:
          type: string
          description: The key of the tag
          maxLength: 128
        value:
          type: string
          description: The value of the tag
          maxLength: 256
      required:
      - key
    TracingConfiguration:
      type: object
      description: Tracing configuration for a state machine
      properties:
        enabled:
          type: boolean
          description: When set to true, X-Ray tracing is enabled
    ListStateMachinesOutput:
      type: object
      properties:
        stateMachines:
          type: array
          description: List of state machines
          items:
            $ref: '#/components/schemas/StateMachineListItem'
        nextToken:
          type: string
          description: Pagination token for next page of results
    DescribeStateMachineOutput:
      type: object
      properties:
        stateMachineArn:
          type: string
          description: The ARN of the state machine
        name:
          type: string
          description: The name of the state machine
        status:
          type: string
          description: The current status of the state machine
          enum:
          - ACTIVE
          - DELETING
        definition:
          type: string
          description: The Amazon States Language definition of the state machine
        roleArn:
          type: string
          description: The ARN of the IAM role used by the state machine
        type:
          type: string
          description: The type of state machine
          enum:
          - STANDARD
          - EXPRESS
        creationDate:
          type: string
          format: date-time
          description: The date the state machine was created
        loggingConfiguration:
          $ref: '#/components/schemas/LoggingConfiguration'
        tracingConfiguration:
          $ref: '#/components/schemas/TracingConfiguration'
    StateMachineListItem:
      type: object
      description: Contains details about a state machine
      properties:
        stateMachineArn:
          type: string
          description: The ARN of the state machine
        name:
          type: string
          description: The name of the state machine
        type:
          type: string
          description: The type of state machine
          enum:
          - STANDARD
          - EXPRESS
        creationDate:
          type: string
          format: date-time
          description: The date the state machine was created
    CreateStateMachineInput:
      type: object
      required:
      - name
      - definition
      - roleArn
      properties:
        name:
          type: string
          description: The name of the state machine
          minLength: 1
          maxLength: 80
        definition:
          type: string
          description: The Amazon States Language definition of the state machine
        roleArn:
          type: string
          description: The ARN of the IAM role to use for this state machine
        type:
          type: string
          description: The type of state machine
          enum:
          - STANDARD
          - EXPRESS
        loggingConfiguration:
          $ref: '#/components/schemas/LoggingConfiguration'
        tracingConfiguration:
          $ref: '#/components/schemas/TracingConfiguration'
        tags:
          type: array
          description: Tags to attach to the state machine
          items:
            $ref: '#/components/schemas/Tag'
    UpdateStateMachineInput:
      type: object
      required:
      - stateMachineArn
      properties:
        stateMachineArn:
          type: string
          description: The ARN of the state machine to update
        definition:
          type: string
          description: The Amazon States Language definition of the state machine
        roleArn:
          type: string
          description: The ARN of the IAM role of the state machine
        loggingConfiguration:
          $ref: '#/components/schemas/LoggingConfiguration'
        tracingConfiguration:
          $ref: '#/components/schemas/TracingConfiguration'
    CreateStateMachineOutput:
      type: object
      properties:
        stateMachineArn:
          type: string
          description: The ARN of the created state machine
        creationDate:
          type: string
          format: date-time
          description: The date the state machine was created
  parameters:
    X-Amz-Target-DeleteStateMachine:
      name: X-Amz-Target
      in: header
      required: true
      schema:
        type: string
        enum:
        - AWSStepFunctions.DeleteStateMachine
    X-Amz-Target-CreateStateMachine:
      name: X-Amz-Target
      in: header
      required: true
      schema:
        type: string
        enum:
        - AWSStepFunctions.CreateStateMachine
    X-Amz-Target-DescribeStateMachine:
      name: X-Amz-Target
      in: header
      required: true
      schema:
        type: string
        enum:
        - AWSStepFunctions.DescribeStateMachine
    X-Amz-Target-ListStateMachines:
      name: X-Amz-Target
      in: header
      required: true
      schema:
        type: string
        enum:
        - AWSStepFunctions.ListStateMachines
    X-Amz-Target-UpdateStateMachine:
      name: X-Amz-Target
      in: header
      required: true
      schema:
        type: string
        enum:
        - AWSStepFunctions.UpdateStateMachine
  securitySchemes:
    sigv4Auth:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication
externalDocs:
  description: Amazon Step Functions API Reference
  url: https://docs.aws.amazon.com/step-functions/latest/apireference/