API
Category: Integration
Node id: api
Makes HTTP API requests with configurable method, headers, authentication, and retry logic
What it does
- Full HTTP client with all standard methods (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS)
- Authentication: Bearer token, Basic auth, API key, or custom headers
- Query parameters from config (templated) and from inputs (inputs win per key)
- Configurable redirect following behavior
- Retries with exponential backoff and jitter; Retry-After honoured on 429/503
- Automatic JSON response parsing when Content-Type is application/json
- Response duration tracking in milliseconds
Use cases
- Call external REST APIs to fetch or submit data within a pipeline
- Integrate with healthcare APIs (Epic, Cerner) using bearer tokens
- Query third-party services and pass structured responses downstream
- Perform authenticated API calls with automatic retry on transient failures
Runtime
- Performance tier:
variable
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
url | text | No | Request URL (overrides config) |
body | any | No | Request body payload |
query_params | json | No | Query parameters as key-value pairs |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Full API response object with status_code, headers, body, and body_json |
success | boolean | No | Whether the request was successful (2xx) |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| URL | url | string | No | API endpoint URL | ||
| HTTP Method | method | enum | No | GET | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | HTTP method |
| Query Parameters | query_params | json | No | Query parameters as key-value pairs; values may use {{variables}}. The query_params input overrides a key |
Auth
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Auth Type | auth_type | enum | No | bearer, basic, api_key, custom | Authentication type | |
| Bearer Token | auth_token | secret | No | Bearer token for authentication | ||
| Username | auth_username | string | No | Username for basic authentication | ||
| Password | auth_password | secret | No | Password for basic authentication | ||
| API Key | api_key | secret | No | API key value | ||
| API Key Header | api_key_header | string | No | X-API-Key | Header name for API key |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Headers | headers | json | No | Custom HTTP headers as key-value pairs | ||
| Timeout (seconds) | timeout | number | No | 30 | min 1 | Request timeout in seconds |
| Follow Redirects | follow_redirects | boolean | No | true | Whether to follow HTTP redirects | |
| Retry Count | retry_count | number | No | 0 | min 0; max 10 | Number of retry attempts on failure |
| Retry Delay (ms) | retry_delay_ms | number | No | 1000 | min 0 | Delay before the first retry in milliseconds; later retries multiply it by retry_backoff_factor |
| Backoff Factor | retry_backoff_factor | number | No | 2 | min 1; max 10 | Multiplier applied to the delay after each failed attempt (1 = fixed delay) |
| Max Retry Delay (ms) | retry_max_delay_ms | number | No | 30000 | min 1 | Upper bound for any single wait, including a server's Retry-After (at least 1 ms; a Retry-After above it waits the bound) |
| Retry Jitter | retry_jitter | boolean | No | true | Randomise each delay by ±10% so parallel callers do not retry in lockstep | |
| Error Body Excerpt (bytes) | error_body_bytes | number | No | 0 | min 0; max 256 | Quote up to this many bytes of a non-2xx response body in the failure message (0 = none, the default). The excerpt may contain patient data and is stored in run history and logs; enable only for endpoints whose error bodies are known to carry none |
Errors
| Code | Description |
|---|---|
MISSING_URL | URL is required via config or input but was not provided |
REQUEST_FAILED | API request failed after all retry attempts |
AUTH_TOKEN_MISSING | auth_token is required for bearer authentication but was empty |
AUTH_CREDENTIALS_MISSING | Username is required for basic authentication but was empty |
UNSUPPORTED_AUTH_TYPE | Provided auth_type is not one of: bearer, basic, api_key, custom |
Runtime notes
- result.body_json is only present when the response Content-Type is application/json — always check before wiring to JSON-expecting nodes
- success is true for any 2xx status; non-2xx responses still populate result with status_code and body for error handling
- URL from the input port overrides the config URL — use this for dynamic endpoint routing in loops
- Retries wait retry_delay_ms × retry_backoff_factor^(n-1) (±10% jitter, capped at retry_max_delay_ms); on 429/503 a Retry-After header sets a longer wait. After the last attempt the node errors with the attempt count and HTTP status (plus a body excerpt only when error_body_bytes > 0 — it may contain patient data and lands in run history)
- With retry_count 0 a 429/503 error still carries Retry-After, so the node-level retry middleware waits at least that long
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Something unclear? Send documentation feedback by email.