Vantage documentation

Agent API fetch

net.fetch is Vantage's direct agent HTTP client. Use it for APIs and machine-readable HTTP resources when rendering a page adds no value. It is intentionally small and easy to reconstruct from memory.

Remember this

vant agent fetch URL '{"method":"POST","headers":{"Content-Type":"application/json"},"body":"{\"hello\":\"world\"}"}'

RPC contract

net.fetch {
  url: string,                    // required; http or https
  method?: string,                // default GET
  headers?: object<string,string>,
  body?: string,                  // exact request bytes
  timeout_ms?: integer,           // default 15000; 1000..25000
  max_bytes?: integer             // default 1 MiB; max 4 MiB
}
=> {
  status: integer,
  ok: boolean,                    // true for HTTP 2xx
  url: string,
  headers: object<string,string>,
  body: string,
  body_encoding: "text" | "base64",
  truncated: boolean,
  bytes: integer
}

GET

vant agent fetch https://api.example.com/status
vant agent --json fetch https://api.example.com/status

POST JSON

vant agent fetch https://api.example.com/items '{
  "method":"POST",
  "headers":{"Content-Type":"application/json","Accept":"application/json"},
  "body":"{\"name\":\"example\",\"enabled\":true}"
}'

Authentication and headers

vant agent fetch https://api.example.com/me '{
  "headers":{"Authorization":"Bearer REDACTED","X-Request-ID":"agent-run-42"}
}'

Important: net.fetch is application-side and does not silently copy cookies, local storage or credentials from the active page. Supply API authentication explicitly. This avoids accidentally attaching the user's browser session to unrelated requests.

Raw request bodies

body is transmitted as its exact string bytes. Vantage does not guess JSON, form, GraphQL or text semantics. Set Content-Type explicitly when the server requires it.

# form
vant agent fetch https://api.example.com/token '{"method":"POST","headers":{"Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials&scope=read"}'

# GraphQL
vant agent fetch https://api.example.com/graphql '{"method":"POST","headers":{"Content-Type":"application/json"},"body":"{\"query\":\"{ viewer { id } }\"}"}'

Response semantics

HTTP 404/500 responses are successful RPC calls: inspect status and ok. Network/transport failures are RPC errors with fetch_error. UTF-8 bodies are returned as text; binary/non-UTF-8 bodies are base64 with body_encoding:"base64". bytes is the response body size as best known: the declared Content-Length when present, otherwise the number of body bytes read up to the max_bytes cap. truncated is true when the response body exceeded max_bytes; for an unknown-length (chunked) response that was truncated, the true full size is not reported.

Behavior details

• timeout_ms is a read/idle timeout (seconds are rounded up), not a hard total-deadline. A slow-but-streaming endpoint may survive a short value.
• Redirects are not auto-followed. A 3xx response is returned as-is with its Location header; follow it with another request when needed.
• No default User-Agent is sent; set one via headers if the target requires it.
• A body without an explicit Content-Type header is sent as application/octet-stream.
• Browser cookies are never attached; supply API authentication explicitly.

Fetch vs page operations

API / JSON / HTTP resource?          -> net.fetch
Need browser login/DOM/rendering?     -> browser.* + page.*
Need page-origin fetch semantics?     -> page.javascript with window.fetch()

page.javascript obeys page-origin/CORS rules. net.fetch is a direct application-side HTTP request and is not constrained by page CORS.

Failure recovery

vant agent call describe '{"name":"net.fetch"}'
vant agent --json fetch https://api.example.com/status

Do not blindly retry non-idempotent POST/PATCH/DELETE requests. Inspect the error and API semantics first; use API-provided idempotency keys where available.