Use the HTTP Request action to call any REST API — handle auth, parse responses, manage rate limits, and implement back-off strategies for robust integrations.
Using the HTTP Request action
The HTTP Request action is the most flexible way to call any external API. Configure the method (GET, POST, PUT, PATCH, DELETE), the URL (which can include dynamic expressions like `{{steps.trigger.output.userId}}`), headers, query parameters, and request body. For JSON APIs, set the Content-Type header to `application/json` and use the Body editor to build the JSON payload with dynamic values. The action returns the HTTP status code, response headers, and parsed response body as separate output fields accessible to downstream nodes. Enable the Parse JSON Response toggle to automatically parse JSON strings into structured objects.
Managing authentication
Cotonity supports several authentication patterns for external APIs. For Bearer token auth, add an Authorization header with value `Bearer {{secrets.MY_API_TOKEN}}` — the `secrets` namespace references credentials stored in your workspace's Secret Manager, which encrypts them at rest and never exposes them in run logs. For Basic Auth, use the dedicated username and password fields in the HTTP Request action. For OAuth2 APIs, register the integration in Settings > Integrations so that Cotonity handles token refresh automatically. Never hardcode API keys directly in header values or URL parameters; always use the Secret Manager.
Handling API responses
After an HTTP request completes, check the `statusCode` output field to verify the call succeeded. For REST APIs, a 2xx code indicates success; 4xx codes indicate a client error (bad request, unauthorized, not found); 5xx codes indicate a server error. Add a Branch node after critical HTTP calls to route the flow based on the status code: a 200 path continues to the next productive step, while an error path logs the failure, stores it in memory, or triggers a notification. For paginated APIs, use a Loop node that increments a page offset or follows a `next` cursor until the API returns an empty page.
Rate limiting and back-off strategies
Many external APIs enforce rate limits that, when exceeded, return a 429 Too Many Requests response. Cotonity's built-in retry logic can handle these automatically: in the HTTP Request action, enable Retry on 429 and set an initial delay and multiplier to implement exponential back-off. For APIs with strict per-minute quotas, add a Delay node between iterations of a loop to pace your requests. Monitor your external API usage in the agent's Run Logs — the HTTP Request action records request duration and status code for every call, making it straightforward to identify rate-limit issues and adjust your timing accordingly.