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, so an API key you put in a header or query parameter is stored with the flow like any other setting: keep those values out of examples and 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. The body is always sent as JSON, and a query parameter here replaces one of the same name in the URL. | 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 copies the request headers into the result, including any key you put in them; 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. The address the Agent gives is requested as it stands, with your headers attached, so instruct the Agent narrowly and avoid broad write or delete endpoints.
Limitations
API Request does not provide OAuth, retries, pagination, multipart uploads, response-schema validation, or complete cURL support. It sends one request to one address. 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.