canonical: https://jentic.com/apis/amazonaws.com/aws-step-functions # AWS Step Functions Jentic publishes the only available OpenAPI specification for AWS Step Functions, keeping it validated and agent-ready. Step Functions coordinates distributed applications and microservices using state machines defined in Amazon States Language (ASL). Agents can create state machines and activities, start standard or express executions, send task success or failure for activity workers, inspect execution history step by step, and run Map runs over large iterables. The 26 operations cover state machines, executions, activities, map runs, and execution history. ## For AI agents Run, monitor, and orchestrate AWS Step Functions state machine executions. Agents can start executions, send task results, fetch execution history, and manage activities and Map runs. ## Scope Does not run general-purpose code, host containers, or queue messages - use only for orchestrating tasks across other AWS services via state machines. ## Capabilities - Create and update state machines using Amazon States Language definitions - Start standard or express executions with StartExecution and StartSyncExecution - Send task results from activity workers with SendTaskSuccess, SendTaskFailure, SendTaskHeartbeat - Inspect step-by-step execution history with GetExecutionHistory - Manage activities (long-poll task workers) via CreateActivity and GetActivityTask - Track distributed Map runs via DescribeMapRun and ListMapRuns - Stop a running execution with StopExecution ## Use cases ### Long-Running Workflow Orchestration Engineering teams use Step Functions to coordinate multi-step workflows - order processing, data pipelines, ML training - that mix Lambda, ECS, SQS, and human approval steps. CreateStateMachine registers the ASL definition, StartExecution kicks off a run with input JSON, and DescribeExecution plus GetExecutionHistory give complete observability into every state transition. Example prompt: CreateStateMachine with the ASL definition and roleArn, then StartExecution with stateMachineArn and JSON input, and DescribeExecution to confirm Status=RUNNING. ### Activity Worker Integration When workflows must wait for a human step or an external worker, Step Functions activities are used. CreateActivity registers a queue, workers long-poll with GetActivityTask, and report results via SendTaskSuccess or SendTaskFailure. SendTaskHeartbeat keeps the task alive while work is in progress. Example prompt: GetActivityTask polling for activityArn, perform the work, then call SendTaskSuccess with the taskToken and a JSON output payload. ### Distributed Map for Bulk Processing Distributed Map mode runs a sub-state-machine across thousands of items in S3 in parallel. Operators use ListMapRuns, DescribeMapRun, and UpdateMapRun to throttle concurrency, track item-level progress, and recover from partial failures. Example prompt: DescribeMapRun for a mapRunArn returned by an execution, inspect itemsProcessed and toleratedFailureCount, then UpdateMapRun to lower maxConcurrency if the downstream system is overloaded. ### AI Agent Workflow Control via Jentic AI agents using Jentic can launch and inspect Step Functions executions on demand: starting a workflow with a generated input, polling its status, and posting back task results from activity workers. Through Jentic, the agent searches by intent, loads operation schemas, and executes against vault-stored AWS credentials. Example prompt: Search Jentic for 'start a step functions execution', execute StartExecution with stateMachineArn and JSON input, then poll DescribeExecution until Status is SUCCEEDED, FAILED, or TIMED_OUT. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /#X-Amz-Target=AWSStepFunctions.CreateStateMachine | Create a state machine from an ASL definition | | POST | /#X-Amz-Target=AWSStepFunctions.DescribeStateMachine | Fetch a state machine's definition and metadata | | POST | /#X-Amz-Target=AWSStepFunctions.DescribeExecution | Inspect a single execution's status and output | | POST | /#X-Amz-Target=AWSStepFunctions.GetExecutionHistory | Retrieve the step-by-step history of an execution | | POST | /#X-Amz-Target=AWSStepFunctions.GetActivityTask | Long-poll for the next activity task | | POST | /#X-Amz-Target=AWSStepFunctions.ListExecutions | List executions for a state machine | | POST | /#X-Amz-Target=AWSStepFunctions.DescribeMapRun | Inspect a distributed Map run | ## Key resources - **State Machines** — ASL workflow definitions; CreateStateMachine, DescribeStateMachine, UpdateStateMachine, DeleteStateMachine, ListStateMachines - **Executions** — Workflow runs; StartExecution, StartSyncExecution, DescribeExecution, StopExecution, ListExecutions - **Activities** — Long-poll task queues; CreateActivity, DeleteActivity, DescribeActivity, GetActivityTask, ListActivities - **Task Tokens** — Async task results; SendTaskSuccess, SendTaskFailure, SendTaskHeartbeat - **Map Runs** — Distributed Map sub-runs; DescribeMapRun, ListMapRuns, UpdateMapRun - **Execution History** — Step-by-step trace; GetExecutionHistory ## Why Jentic - **Setup:** Wiring AWS Step Functions by hand means computing SigV4 signatures, picking the right regional states host, and routing calls through the X-Amz-Target action header yourself. Through Jentic you install once, import Step Functions from the API Directory, store the access keys once, and your agent calls it. - **Permission scoping:** Step Functions routes its actions through one endpoint by X-Amz-Target rather than resource ids in the path, so scope the agent to the operations it needs, such as StartExecution and GetExecutionHistory. You choose the operations it may call, so destructive ones like DeleteStateMachine are not included unless you add them. - **Credential handling:** Your AWS access keys are stored once, encrypted, by your own Jentic One instance and used to sign each Step Functions request with SigV4 at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'start a Step Functions execution' or 'get execution history', and Jentic returns the matching Step Functions operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **AWS Lambda** — Serverless compute that runs the function tasks within most state machines - **Amazon Simple Workflow Service** — Older AWS workflow service preceding Step Functions, kept for legacy use cases - **Amazon EventBridge** — Event bus that triggers Step Functions executions on schedule or in response to AWS service events ## FAQ ### Why is there no official OpenAPI spec for AWS Step Functions? AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AWS Step Functions via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the AWS Step Functions use? Step Functions uses AWS Signature Version 4 with IAM credentials and permissions on the states:* actions. Through Jentic, AWS keys live encrypted in the vault and SigV4 signing is performed server-side - the agent never holds the raw credential. ### Can I run a Step Functions execution synchronously? Yes, but only for Express workflows. StartSyncExecution invokes an Express state machine and blocks until completion, returning the output inline. Standard workflows must be started with StartExecution and polled via DescribeExecution. ### What are the rate limits for the AWS Step Functions? Step Functions throttles per-region: StartExecution is roughly 1300 per second on Standard and 6000 per second on Express in commercial regions, while StateTransition counts apply to long-running Standard executions. Throttled calls return ThrottlingException; retry with exponential backoff. ### How do I post a task result from an activity worker through Jentic? Through Jentic, search for 'send task success step functions', load the SendTaskSuccess schema, and execute with the taskToken (received from GetActivityTask) and a JSON output string. SendTaskFailure handles error cases and SendTaskHeartbeat keeps the token alive during long work. ### Is AWS Step Functions free? Step Functions Standard charges per state transition (a free tier of 4,000 transitions per month applies). Express workflows are billed per request and per duration. See https://aws.amazon.com/step-functions/pricing/ for the current rates. ### Can I limit what my agent is allowed to do with the AWS Step Functions API? Yes. Because you run Jentic One yourself, your own rules decide which Step Functions operations and AWS credentials the agent may use. Step Functions routes every action through one endpoint by the X-Amz-Target header rather than by resource paths, so you scope the agent to just the operations it needs, such as StartExecution and GetExecutionHistory. Destructive actions like DeleteStateMachine or StopExecution stay out of reach unless you explicitly add them.