`http_request`

Generic HTTP request with configurable method.

Parameters

methodstringdefault "GET": HTTP method. Supported values: GET, POST, PUT, DELETE, PATCH.
urlstringrequired: Request URL. Supports context interpolation via ${ctx.key}.
headersobjectdefault {}: Key-value map of request headers. Header values support ${ctx.key} interpolation.
body_typestringdefault "json": Body encoding. Supported values: json, form, text.
bodyany: Request body payload.
timeoutnumberdefault 30: Request timeout in seconds (supports fractional values).
authobject: Authentication configuration. See [Auth](#auth) below.
output_keystringdefault "http": Prefix for context output keys.
fail_on_statusbooleandefault true: When true, non-2xx responses return an error after any configured status retries. When false, non-2xx responses are returned as normal output.
retry_statusesarraydefault []: HTTP status codes to retry, as numbers or numeric strings.
status_retriesintegerdefault 0: Number of retries for responses whose status appears in retry_statuses.
max_status_retriesintegerdefault 0: Alias for status_retries.
status_retry_backoffnumberdefault 1: Base retry delay in seconds. Delay uses exponential backoff by attempt.
respect_retry_afterbooleandefault true: When true, a numeric Retry-After response header overrides the backoff delay.
max_retry_afternumberdefault 60: Maximum status retry delay in seconds.
max_redirectsintegerdefault 10: Maximum number of redirects to follow. Set to 0 to disable redirect following.
block_private_networkbooleandefault false: When true, refuses the request (and any redirect hop) if the target host is localhost or a literal private/loopback/link-local IP, including the cloud-metadata address 169.254.169.254. A hostname that resolves to an internal address via DNS is not detected.

For body_type = "json", string values in body are recursively interpolated via ${ctx.key}.

For body_type = "form", body must be a JSON object. Keys/values are percent-encoded and sent as application/x-www-form-urlencoded.

For body_type = "text", body is converted to plain text after recursive interpolation. Non-string values are stringified.

Auth

The auth object supports three authentication types, determined by auth.type:

`auth.type`	Fields	Behavior
`"bearer"`	`token` (string)	Sets the `Authorization: Bearer <token>` header. Default when `auth.type` is omitted. Token supports `${ctx.key}` interpolation.
`"basic"`	`username` (string), `password` (string)	Sets basic authentication. `username` defaults to `""` if omitted. `password` is optional.
`"api_key"`	`key` (string), `header` (string)	Sets a custom header with the API key. `header` defaults to `"X-API-Key"`. Key supports `${ctx.key}` interpolation.

Context Output

On a successful response (HTTP 2xx), or on a non-2xx response when fail_on_status = false, the following keys are written to the context:

{output_key}_status -- HTTP status code as a number (e.g., 200).
{output_key}_data -- Response body parsed as JSON. Falls back to a plain string if JSON parsing fails.
{output_key}_headers -- Response headers as a key-value object.
{output_key}_success -- Boolean true for HTTP 2xx, false otherwise.
{output_key}_attempts -- Number of HTTP attempts, including the first request and any status retries.

By default, non-success responses (non-2xx) return an error after the response is read. Set fail_on_status = false when the flow should inspect provider error responses, such as 401, 402, 429, or 5xx bodies and headers.

With the default output_key of "http", the keys are: http_status, http_data, http_headers, http_success, http_attempts.

Status Retries

Status retries are separate from step-level retries. They retry only HTTP responses whose status is listed in retry_statuses; transport errors still surface as node errors and can be handled by step retry configuration.

flow:step("provider_call", nodes.http_request({
    method = "POST",
    url = "https://api.example.com/generate",
    body = { prompt = "${ctx.prompt}" },
    output_key = "provider",
    fail_on_status = false,
    retry_statuses = { 429, 500, 502, 503 },
    status_retries = 2,
    status_retry_backoff = 0.5,
    respect_retry_after = true,
    max_retry_after = 10
}))

Example

local flow = Flow.new("create_user")

flow:step("request", nodes.http_request({
    method = "POST",
    url = "https://api.example.com/users",
    headers = { ["Content-Type"] = "application/json" },
    body = { name = "Alice", email = "[email protected]" },
    auth = { type = "bearer", token = "${ctx.api_token}" },
    timeout = 10,
    output_key = "create_user"
}))

flow:step("done", nodes.log({
    message = "Created user: ${ctx.create_user_status}",
    level = "info"
})):depends_on("request")

return flow