http_request
Perform an HTTP request and return a compact schema of the response, enabling token-efficient data extraction by fetching only needed fields via jq masks.
Instructions
Perform an HTTP request and return a compact schema of the response, not the full body.
Default flow (use this for any non-trivial response): (1) call http_request to get { schema, cache_id }; (2) call http_read with cache_id and a jq mask to extract only the field(s) you need. This keeps your context small even on multi-MB responses.
body_mode controls how much of the body comes back inline: schema (no body — schema only) head (schema + truncated preview of arrays/strings — middle ground) inline (schema + full body — costly; capped by PEEK_INLINE_BODY_CAP) auto (default — server picks based on byte thresholds) Reach for inline ONLY when body is known-small AND every field is needed; a 200KB JSON inlined is ~12K tokens of context for data you may never use.
Multipart uploads stream files via chunked transfer encoding (no Content-Length). Most servers accept this; some legacy proxies / primitive test servers reject it.
Cookbook: • Explore an unknown endpoint: http_request {method: "GET", url} → schema shows what is there http_read {cache_id, mask: ".data | map({id, name})"} • Top 10 GitHub issues by comment count: http_request {method: "GET", url: "https://api.github.com/repos/OWNER/REPO/issues"} http_read {cache_id, mask: "sort_by(-.comments)[:10] | .[] | {id, title, comments}"}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| method | Yes | ||
| url | Yes | Absolute URL. | |
| query | No | ||
| headers | No | ||
| body | No | Object → JSON; string → text/plain; mutually exclusive with body_raw and multipart. | |
| body_raw | No | Raw payload; pair with content_type. | |
| multipart | No | ||
| content_type | No | Override Content-Type. | |
| timeout_ms | No | Default 30000. | |
| follow_redirects | No | Default true (max 10 hops). | |
| tls_insecure | No | Default false. | |
| schema_format | No | Default 'paths'. | |
| body_mode | No | Default 'auto'. schema | head | inline | auto. | |
| download_to | No | Stream body to file (skips cache). |