HTTP Request Action

The http_request action allows you to call external APIs from your automations and chat sessions. It supports all standard HTTP methods and includes built-in security protections.

Prerequisites

VirtuousAI account with CLI installed
Understanding of Automations
Familiarity with Actions

Overview

Use http_request to integrate with third-party APIs, fetch data from external services, or trigger webhooks in other systems.

Supported Methods: GET, POST, PUT, DELETE, PATCH

Definition Schema

When using http_request in an automation or action definition:

{
  "kind": "http_request",
  "method": "GET",
  "url": "https://api.example.com/endpoint",
  "headers": {
    "Authorization": "Bearer token"
  },
  "params": {
    "page": "1"
  },
  "body": {
    "key": "value"
  },
  "timeout_seconds": 30,
  "follow_redirects": true,
  "max_redirects": 5,
  "retry_non_idempotent": false
}

Configuration Options

Option	Type	Required	Default	Description
`kind`	string	Yes	-	Must be `"http_request"`
`method`	string	Yes	-	HTTP method: GET, POST, PUT, DELETE, PATCH
`url`	string	Yes	-	Target URL (HTTPS required in production)
`headers`	object	No	`{}`	Request headers
`params`	object	No	`{}`	Query string parameters
`body`	object	No	`null`	JSON request body (for POST/PUT/PATCH)
`timeout_seconds`	number	No	`30`	Request timeout (max: 300)
`follow_redirects`	boolean	No	`true`	Whether to follow HTTP redirects
`max_redirects`	number	No	`5`	Maximum number of redirects to follow
`retry_non_idempotent`	boolean	No	`false`	Enable retries for POST/PUT/PATCH

Response Schema

After execution, the action returns:

{
  "status_code": 200,
  "body": {},
  "body_truncated": false,
  "body_encoding": null,
  "original_size_bytes": 1234,
  "headers": {
    "content-type": "application/json"
  },
  "duration_ms": 150.5,
  "time_to_first_byte_ms": 45.2,
  "redirect_count": 0,
  "final_url": "https://api.example.com/endpoint",
  "request_redacted": {}
}

Field	Description
`status_code`	HTTP response status code
`body`	Parsed JSON or text response
`body_truncated`	`true` if response exceeded 100KB limit
`body_encoding`	`"utf-8"`, `"base64"`, or `null` (JSON)
`original_size_bytes`	Original response size before truncation
`headers`	Response headers
`duration_ms`	Total request duration in milliseconds
`time_to_first_byte_ms`	Time to first byte in milliseconds
`redirect_count`	Number of redirects followed
`final_url`	Final URL after redirects
`request_redacted`	Request details with sensitive headers masked

CLI / Chat Tool Usage

When using http_request as a chat tool, the interface is simplified:

vai chat
> Use http_request to GET https://api.github.com/users/octocat

The chat tool accepts these parameters:

method - HTTP method
url - Target URL
headers - Request headers (optional)
body - Request body for POST/PUT/PATCH (optional)
timeout_seconds - Timeout in seconds (optional)

Examples

GET Request

Fetch data from an external API:

vai actions create \
  --name "Fetch GitHub User" \
  --config '{
    "kind": "http_request",
    "method": "GET",
    "url": "https://api.github.com/users/octocat",
    "headers": {
      "Accept": "application/vnd.github.v3+json"
    }
  }'

curl -X POST https://vai-dev.virtuousai.com/api/v1/actions \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fetch GitHub User",
    "config": {
      "kind": "http_request",
      "method": "GET",
      "url": "https://api.github.com/users/octocat",
      "headers": {
        "Accept": "application/vnd.github.v3+json"
      }
    }
  }'

POST with JSON Body

Send data to an external API:

vai actions create \
  --name "Create Item" \
  --config '{
    "kind": "http_request",
    "method": "POST",
    "url": "https://api.example.com/items",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer your-token"
    },
    "body": {
      "name": "New Item",
      "description": "Item description"
    }
  }'

curl -X POST https://vai-dev.virtuousai.com/api/v1/actions \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Create Item",
    "config": {
      "kind": "http_request",
      "method": "POST",
      "url": "https://api.example.com/items",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer your-token"
      },
      "body": {
        "name": "New Item",
        "description": "Item description"
      }
    }
  }'

Security

VirtuousAI includes multiple security protections for HTTP requests.

HTTPS Enforcement

Environment	Rule
Production	Only HTTPS URLs are allowed
Development	HTTP allowed for `localhost` and `127.0.0.1` only

SSRF Protection

All URLs are validated before requests are made to prevent Server-Side Request Forgery:

DNS resolution is checked to prevent requests to private/internal IPs
Blocked IP ranges: private, loopback, link-local, reserved
Redirect targets are also validated (prevents redirect-based SSRF)

Requests to internal networks, private IP ranges, and cloud metadata endpoints are blocked for security.

Sensitive Header Redaction

The following headers are automatically redacted in logs and stored results:

Authorization
X-Api-Key
Api-Key
X-Auth-Token
Cookie
Set-Cookie

The request_redacted field in the response shows the request with these headers masked.

Limits

Limit	Value
Max response body	100 KB (truncated if exceeded)
Default timeout	30 seconds
Max timeout	300 seconds
Max redirects	5 (configurable)

If a response exceeds 100KB, it will be truncated and body_truncated will be set to true. The original_size_bytes field shows the full size.

Error Handling

Error Code	Description	Retryable
`invalid_url`	URL validation failed (non-HTTPS, invalid hostname)	No
`redirect_to_private_ip`	Redirect led to blocked IP	No
`http_4xx`	Client error (400-499)	No
`http_5xx`	Server error (500-599)	Yes (GET/DELETE only)
`timeout`	Request timed out	Yes (GET/DELETE only)
`request_error`	Network/connection error	Yes (GET/DELETE only)

By default, only idempotent methods (GET, DELETE) are retried on failure. Set retry_non_idempotent: true to enable retries for POST, PUT, and PATCH methods.

HTTP Request Action

HTTP Request Action

Overview

Definition Schema

Configuration Options

Response Schema

CLI / Chat Tool Usage

Examples

GET Request

POST with JSON Body

Security

HTTPS Enforcement

SSRF Protection

Sensitive Header Redaction

Limits

Error Handling

Next Steps

Building Automations

Webhook Integration

Actions Reference

On this page