Callable id: web::fetch — pass to agent_trigger { function: "web::fetch" } (NOT the iii://... skill path; that's docs, not a function id). Use this instead of shell::exec with curl/wget for any HTTP request: you get a parsed { ok, status, headers, body } envelope, enforced size/timeout caps, and server-side SSRF protection a shell curl doesn't have.

Decide fast

You want to…	Call
Read a web page (docs, articles)	{ "url": "https://…", "format": "markdown" }
GET a page/API	{ "url": "https://…" }
Parse a JSON API response	{ "url": "https://…", "response_format": "json" }
POST/PUT JSON	{ "url": "…", "method": "post", "json": { … } }
Send a raw body / form	{ "url": "…", "method": "post", "body": "…", "headers": { "content-type": "…" } }
Download binary	{ "url": "…", "response_format": "base64" }
Run a shell curl	❌ stop — use web::fetch

Minimal call

// agent_trigger { function: "web::fetch", payload: { "url": "https://api.github.com/zen" } }
// → { "ok": true, "status": 200, "body": "Design for failure.", ... }

That's the whole T0 path: a URL is the only required field. Everything else has a default.

Read the result correctly (the #1 trap)

ok tells you if the request COMPLETED, not whether the server was happy.

• A 404 or 500 is a successful fetch → ok: true, status: 404. Branch on status for HTTP outcomes.
• ok: false means the request never produced a response (bad URL, blocked host, timeout, transport failure). Branch on error for those.

if (!r.ok)            → fetch failed; look at r.error  (see table below)
else if (r.status>=400) → server returned an HTTP error; look at r.status / r.body
else                  → success; use r.body or r.json

Do not treat ok: true as "2xx". Always check status too.

One exception: in page-reading mode (format set), an image/* response returns the image itself plus a one-line text summary instead of this envelope — there is no top-level ok/status to branch on (see "Images in page-reading mode" below).

Request fields

Field	Default	Notes
url (required)	—	absolute http(s)://
method	GET	case-insensitive ("post" works); GET HEAD POST PUT PATCH DELETE OPTIONS
headers	{}	object; keys as you write them
json	—	structured payload; auto-stringified + sets content-type: application/json. Wins over body.
body	—	raw string body; use for non-JSON. Ignored on GET/HEAD.
response_format	"text"	"text" | "base64" (binary) | "json" (also parses into json)
format	—	page-reading mode: "markdown" (HTML→Markdown) | "text" (HTML→plain text) | "html" (raw). Sends a browser UA + matching Accept; retries once with the honest UA on a Cloudflare challenge; images come back viewable. Forces text transport (response_format ignored).
timeout_ms	30000	clamped DOWN to the worker ceiling (120000 by default); can't raise past it
max_bytes	5 MiB (256 KiB in format mode)	raw fetches default to the 5 MiB ceiling; page-reading mode (format set) uses a context-safe 256 KiB. Pass an explicit value to override (up to the 5 MiB ceiling). Over-cap body is truncated, not errored
follow_redirects	true	each hop re-checked against the SSRF blocklist

Content pipeline

Four request controls for page-reading mode (format set):

Field	Effect
content_filter	{ type: "pruning"|"bm25", query?, threshold?, threshold_type?, min_word_threshold? } — filters body to signal content. Pruning default threshold 0.48; BM25 default 1.0. query falls back to page