> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Request

> Make HTTP requests to external APIs with security controls

## Overview

The HTTP tool allows making HTTP requests to external APIs with comprehensive security controls including SSRF protection, credential injection, leak detection, and size limits.

## http

Make HTTP requests to external APIs. Supports GET, POST, PUT, DELETE, PATCH methods.

**Input Parameters**

<ParamField path="method" type="string" required>
  HTTP method. Must be one of: GET, POST, PUT, DELETE, PATCH
</ParamField>

<ParamField path="url" type="string" required>
  The URL to request (must be HTTPS)
</ParamField>

<ParamField path="headers" type="array">
  Optional headers as a list of objects with `name` and `value` properties
</ParamField>

<ParamField path="body">
  Request body for POST/PUT/PATCH. Can be a JSON object, array, string, or other value.
</ParamField>

<ParamField path="timeout_secs" type="integer" default={30}>
  Request timeout in seconds
</ParamField>

**Output**

<ResponseField name="status" type="integer">
  HTTP status code
</ResponseField>

<ResponseField name="headers" type="object">
  Response headers as key-value pairs
</ResponseField>

<ResponseField name="body">
  Response body parsed as JSON if possible, otherwise as string
</ResponseField>

**Example Request**

```json theme={null}
{
  "method": "POST",
  "url": "https://api.example.com/users",
  "headers": [
    {"name": "Content-Type", "value": "application/json"}
  ],
  "body": {
    "name": "Alice",
    "email": "alice@example.com"
  },
  "timeout_secs": 10
}
```

**Example Response**

```json theme={null}
{
  "status": 201,
  "headers": {
    "content-type": "application/json",
    "x-request-id": "abc-123"
  },
  "body": {
    "id": "user_789",
    "name": "Alice",
    "email": "alice@example.com"
  }
}
```

## Security Features

### HTTPS-Only

Only HTTPS URLs are allowed. HTTP requests are rejected to prevent credential leakage.

### SSRF Protection

* Localhost and private IP addresses blocked (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
* DNS rebinding protection: all resolved IPs are checked before connection
* Cloud metadata endpoints blocked (169.254.169.254)
* Redirects blocked to prevent SSRF via redirect chains

### Leak Detection

* Outbound requests scanned for secrets in URL, headers, and body
* Inbound responses scanned for leaked credentials
* Automatic credential scrubbing from error messages

### Size Limits

* Maximum response size: 5MB
* Pre-flight Content-Length check to reject oversized responses before download
* Streamed reading with hard size cap even if server lies about size

### Credential Injection

When configured with a credential registry:

* API keys and tokens automatically injected based on host
* Credentials fetched from encrypted secrets store
* Injected as headers or query parameters per configuration
* Never exposed to LLM or logged

### HTML to Markdown

When the `html-to-markdown` feature is enabled:

* HTML responses automatically converted to Markdown
* Content-Type detection based on response headers
* Falls back to raw HTML if conversion fails

## Approval Requirements

<Warning>
  Requests require explicit approval if:

  * Manual authentication headers present (Authorization, X-API-Key, Cookie, etc.)
  * Target host has credential mappings (auto-injection configured)
  * Otherwise requires approval unless auto-approved by user
</Warning>

### Authentication Headers Detected

The following header names trigger explicit approval (case-insensitive):

* `authorization`
* `x-api-key`
* `cookie`
* `proxy-authorization`
* `x-auth-token`
* `api-key`
* `x-token`
* `x-access-token`
* `x-session-token`
* `x-csrf-token`
* `x-secret`
* `x-api-secret`

Query parameters with credential patterns (e.g., `?api_key=...`) also trigger approval.

## Rate Limiting

* 30 calls per minute
* 500 calls per hour

## Error Conditions

<ResponseField name="InvalidParameters">
  * Invalid URL format
  * Unsupported HTTP method
  * Invalid body JSON
</ResponseField>

<ResponseField name="NotAuthorized">
  * HTTP URL (not HTTPS)
  * Localhost or private IP address
  * Hostname resolves to disallowed IP
  * Redirect detected (SSRF prevention)
  * Outbound leak detected (secrets in request)
</ResponseField>

<ResponseField name="ExternalService">
  * Network error
  * Failed to read response body
</ResponseField>

<ResponseField name="Timeout">
  * Request exceeded timeout (default 30s)
</ResponseField>

<ResponseField name="ExecutionFailed">
  * Response Content-Length exceeds 5MB
  * Response body exceeds 5MB during streaming
</ResponseField>

## Examples

### GET Request

```json theme={null}
{
  "method": "GET",
  "url": "https://api.github.com/repos/rust-lang/rust"
}
```

### POST with JSON Body

```json theme={null}
{
  "method": "POST",
  "url": "https://api.example.com/data",
  "headers": [
    {"name": "Content-Type", "value": "application/json"}
  ],
  "body": {"key": "value"}
}
```

### PUT with String Body

```json theme={null}
{
  "method": "PUT",
  "url": "https://api.example.com/resource/123",
  "body": "plain text content"
}
```

### Custom Timeout

```json theme={null}
{
  "method": "GET",
  "url": "https://slow-api.example.com/data",
  "timeout_secs": 60
}
```