Skip to content
Docs

cap_http_request

Source: cap_http_request.c components/claw_capabilities/cap_http_request/src/cap_http_request.c · header: cap_http_request.h components/claw_capabilities/cap_http_request/include/cap_http_request.h · Skill: SKILL.md components/claw_capabilities/cap_http_request/skills/cap_http_request/SKILL.md

Overview

Section titled “Overview”

cap_http_request exposes a generic http_request tool to the LLM, allowing the Agent to call external HTTP/HTTPS APIs directly. To prevent the LLM from accessing arbitrary network resources, every request must pass the domain allowlist check.

Tool description

Section titled “Tool description”
Tool ID Description
http_request Call a standard HTTP endpoint, supporting GET/POST/PUT/PATCH/DELETE/HEAD

Input parameters

Section titled “Input parameters”
Parameter Type Required Description
url string Yes Request URL; hostname must be in the allowlist
method string HTTP method, default GET. Options: GET, POST, PUT, PATCH, DELETE, HEAD
headers object Custom request headers as key-value pairs
body string Request body
save_path string Save the response body to the specified file path, useful for large downloads
timeout_ms integer Timeout (1-120000ms), default 15000ms
max_body_bytes integer In-memory response body buffer limit (1-65535), default 16384
max_file_bytes integer File write limit in save_path mode (1-2147483647)

Return value

Section titled “Return value”

Returns a JSON object containing:

  • status: HTTP status code
  • body: response body text when save_path is not specified
  • saved_path / saved_bytes: saved file path and byte count when save_path is specified
  • truncated: whether the response was truncated
  • error: error message when the request fails

Allowlist mechanism

Section titled “Allowlist mechanism”

The allowlist is stored in the NVS config key http_allowlist as comma-separated domains:

api.openai.com,httpbin.org,example.com

Validation rules:

  • Extract the hostname from the request URL and match each allowlisted domain case-insensitively
  • Support subdomain matching: allowlisting example.com permits api.example.com
  • HTTP redirect targets must also pass the allowlist check
  • Maximum allowlist length is 320 characters

Registration and configuration

Section titled “Registration and configuration”
#include "cap_http_request.h"

cap_http_request_register_group();
cap_http_request_set_allowlist("api.example.com,httpbin.org");

cap_http_request_set_allowlist is called by the application layer to set the allowlist dynamically from NVS configuration.

Group information

Section titled “Group information”
Property Value
Group ID cap_http_request
Default LLM-visible Yes (edge_agent default initial visible group)
Tool count 1