API Request
On this page
Purpose
API Request sends an HTTP request and returns the response to your flow. Use it for a REST API, webhook, or service that does not already have an Arkus component.
When to use it
- Read data from an API with a GET request.
- Send a JSON payload to a webhook.
- Call an authenticated service with headers or query parameters.
Required setup
Have the endpoint contract, request method, and any required authentication ready. Normal mode needs the endpoint URL, while Agent Core supplies the URL or cURL input in Tool Mode. API Request has no Credential or secret field. Headers, query parameters, and body values are ordinary configuration, so do not put sensitive values in examples or screenshots. API Request is not supported in deployed agents.
How to use it
Tool Mode
- Add API Request, enable Tool Mode, and connect the tool output to Agent Core.
- Configure the method, headers, body, and timeout. Agent Core can supply only the URL or cURL input.
- Test the tool against one narrow endpoint in the Builder.
Normal mode
- Choose URL or cURL mode.
- Enter the URL and method, or paste a cURL command.
- Add query parameters, headers, and a body when the endpoint requires them.
- Connect API Response to a component that can use the returned content.
Configuration
| Setting | What it controls | Recommended starting point |
|---|---|---|
| Mode | Chooses direct URL configuration or cURL import. The default is URL. | Keep URL mode unless you have a tested cURL command. |
| Method | Chooses GET, POST, PATCH, PUT, or DELETE. The default is GET. | Keep GET for retrieval. |
| URL or cURL | URL adds https:// when no scheme is present. cURL import copies only URL, method, headers, and body; it is not a complete cURL runtime. | Use the provider's documented endpoint and inspect imports. |
| Query Parameters, Body, Headers | Adds request data and authentication. | Add only the fields required by the endpoint. |
| Timeout | Limits how long the request can wait. The default is 30 seconds. | Keep the default until the provider needs more time. |
| Follow Redirects | Follows redirects. It is enabled by default. | Leave it enabled unless the endpoint contract says otherwise. |
| Save to File and Include HTTPX Metadata | Save to File returns a temporary file path. Include HTTPX Metadata adds request headers; response status and headers are already returned. | Enable only when a downstream step needs them. |
Expected result
The component returns Data with the URL, status code, response headers, and response body. HTTP 4xx and 5xx responses remain normal response data with their actual status. Connection and timeout failures return error Data with a synthetic status code of 500. Inspect status_code before treating a response as successful.
Reference details
Enable Tool Mode when Agent Core should call one narrowly defined endpoint. The Agent can supply the URL or cURL input, while method, headers, body, and timeout stay configured by the flow author. Avoid broad write or delete endpoints.
Limitations
API Request does not provide OAuth, retries, multipart uploads, response-schema validation, or complete cURL support. A flow that contains API Request is rejected during deployment. Save to File writes to a temporary local path, and non-JSON responses return bytes in result.
Works well with
Send API Response to Data Operations to select or rename fields, or to Parser to format the response as text. In Tool Mode, connect the generated tool to Agent Core. Only URL and cURL are Agent-controlled inputs.