Understand REST API steps

A REST API step sends an outbound HTTP request to an API endpoint during a workflow run. You can use REST API steps to integrate workflows with third-party services and any system that exposes an HTTP interface.

Why use REST API steps in workflows

Automation workflows often need to interact with systems beyond Ansible Automation Platform. REST API steps give you direct HTTP access to external services without writing custom scripts.

Use REST API steps when a workflow includes:

  • Calls to third-party APIs, such as cloud providers, monitoring platforms, or ticketing systems
  • Lookups to services that provide data for downstream decision-making
  • Notifications to external services, such as sending a message to a webhook endpoint
  • Data submissions to external systems after a task agent analysis or an Ansible Automation Platform job completes

How REST API steps work

The REST API step follows this execution pattern:

  1. The workflow engine resolves any expressions in the step configuration, including dynamic values from upstream steps.
  2. The engine constructs the HTTP request using the configured method, URL, headers, and body.
  3. If you configured authentication, the engine retrieves the referenced credential and applies it to the request.
  4. The engine sends the request to the target URL and waits for a response.
  5. The engine captures the response status code, headers, body, and elapsed time, and makes them available to downstream steps.

REST API steps do not follow HTTP redirects. If the target API returns a redirect response, such as 301 or 302, the step captures the redirect response as its output rather than following the redirect.

If the response returns an HTTP error status (4xx or 5xx), the step fails. You can select Continue on failure from the On failure behavior dropdown on the step Settings tab to allow the workflow to proceed despite a failed request.

Note:

URLs that target private network addresses, loopback addresses, or cloud metadata endpoints are blocked by default to prevent server-side request forgery (SSRF). Contact your administrator to configure the allowed hosts list for internal endpoints that your workflows need to reach.

REST API step output

After the step runs, the following output fields are available to downstream steps:

Field Description
status_code The HTTP status code returned by the target server.
body The response body. JSON responses are parsed into structured data that downstream steps can reference by field name.
headers The response headers returned by the target server.
elapsed The elapsed time in seconds between sending the request and receiving the response.

Supported HTTP methods

REST API steps support the following HTTP methods:

Method Use case
GET Retrieve data from an API endpoint.
POST Send data to create a resource or trigger an action.
PUT Replace an existing resource with new data.
PATCH Update specific fields of an existing resource.
DELETE Remove a resource from the target system.

Design idempotent API calls

When you configure retry policies on REST API steps, consider whether the target API can handle repeated calls safely. A step that fails mid-execution might be retried, which can cause unintended duplicate operations on the target system.

Safe to retry:

  • GET requests that only read data
  • PUT requests that replace a resource with the same data
  • Operations that accept an idempotency key or deduplication header
  • Status checks and health endpoints

Unsafe to retry without protection:

  • POST requests that create new resources
  • Requests that send notifications or trigger irreversible actions
  • Financial transactions without deduplication

Recommendations:

  • For non-idempotent operations, select Override retry policy and set Max retries to 0 to disable automatic retries. Without this override, the system default of 3 retries applies to transient HTTP errors (429, 502, 503, 504).
  • Pass ${workflow_context.execution.id} as a deduplication header to give the target API a unique identifier for each workflow run.
  • Optionally, set Continue on failure in the On failure behavior setting to allow the workflow to proceed after a failed request. This controls whether downstream steps run after the step ultimately fails, but it does not prevent retries while the step is still running.

Authentication

REST API steps support the following credential types for secure access to protected endpoints:

  • HTTP Bearer Token: Token-based authentication using a bearer token.
  • HTTP Basic Auth: Username and password authentication.

Select a stored credential from the Authentication credential dropdown in the details panel. Credentials are resolved at runtime and are not exposed in the workflow definition or logs. You can manage credentials in Configuration > Credentials.

Settings

The REST API step supports the following settings on the Settings tab:

  • On failure behavior: Select an option from the dropdown to control what happens when the step fails:

    • System default — Uses the system-wide setting configured by an administrator.
    • Continue on failure — The step is marked as failed and the workflow continues to the next step.
    • Stop workflow or branch on failure — The step fails and the workflow or current branch stops execution.

  • Timeout (seconds): The maximum number of seconds the request can run before the step fails with a timeout error. The default timeout is 30 seconds.

  • Retry policy: Automatic retries are enabled by default. When a request returns a transient error (status codes 429, 502, 503, or 504), the system retries the request using the default policy: 3 retries, 1-second initial interval, 60-second maximum interval, and a backoff coefficient of 2.0. All other error responses fail immediately without retrying. Select Override retry policy to customize the retry behavior or set Max retries to 0 to disable retries entirely. For non-idempotent operations such as POST or DELETE requests, disable retries to prevent duplicate side effects.