web::fetch
Fetch a URL over HTTP(S) and return the response as a structured envelope. Use this INSTEAD of `shell::exec` with curl for any HTTP request — it returns {ok, status, headers, body} as JSON, enforces size/timeout caps, and blocks private / cloud-metadata / link-local addresses server-side (SSRF guard; loopback is allowed by default for harness dev workflows). To READ A WEB PAGE, set `format: "markdown"` — HTML is converted to Markdown and images come back viewable (image responses in that mode return the image itself plus a text line, not the {ok,...} envelope). For JSON: pass `json: {...}` (auto-stringifies + sets content-type) and `response_format: "json"` (auto-parses response into the `json` field). Method is case-insensitive. On failure returns `{ok:false, error, message}` where `error` is one of: invalid_payload, invalid_url, blocked_host, timeout, too_many_redirects, transport_error. Branch on `error`, not on text.
- bodystring
Raw request body as a string. Prefer `json` for JSON payloads.
- follow_redirectsboolean
Follow 3xx redirects. Defaults to true. Each hop is re-checked against the SSRF blocklist.
- formatany of
Page-reading mode: "markdown" | "text" | "html". When set, a browser UA + format Accept header are used, HTML is transformed, and response_format is ignored (treated as "text").
any of (2)variant 1valuestringenum: markdown, text, htmlvariant 2valuenull - headersobject
Request headers. Lower-cased keys recommended.
- jsonunknown
Structured JSON payload. When set, the handler stringifies it and forces `content-type: application/json`; wins over `body`.
- max_bytesinteger· uint64min 0
Cap on response body bytes. Defaults to the worker ceiling for raw fetches, or 256 KiB in page-reading mode (`format` set).
- methodstring
HTTP method. Defaults to GET. Case-insensitive ("get" works).
- response_formatany of
How to return the body: "text" (default), "base64", or "json".
any of (2)variant 1valuestringenum: text, base64, jsonvariant 2valuenull - timeout_msinteger· uint64min 0
Per-request timeout in ms. Capped by the worker's max_timeout_ms.
- urlstringrequired
Absolute http(s):// URL to fetch.
- bodystring
- bytes_truncatedboolean
- contentunknown
- content_typestring
- detailsunknown
- errorstring
- headersobject
- jsonunknown
- messagestring
- okboolean
- parse_errorstring
- redirect_chainstring[]
- response_formatstring
- statusinteger· uint16min 0
- status_textstring
- transformedstring