Fetch

Low-latency raw HTTP fetch with optional conversion. Accessed via client.fetch.

create

client.fetch.create(opts: FetchOpts, requestOptions?: RequestOptions): Promise<FetchResult>

POST /v1/fetch — fetch URL content via POST body.

Resolves a FetchResult — the raw content body plus X-Fetch-* metadata. The body is returned verbatim — a JSON-serving upstream comes back as the raw JSON string, not a parsed object.

requestOptions carries the CLIENT-side abort budget (requestTimeoutMs) and an optional caller signal. It matters most here: the gateway's own ceiling for a fetch is 60 s, so without a per-call budget a slow upstream holds the caller for the constructor default (2 minutes) rather than a duration the caller chose.

get

client.fetch.get(opts: FetchGetOpts, requestOptions?: RequestOptions): Promise<FetchResult>

GET /v1/fetch — fetch URL content via query params.

Resolves a FetchResult — the raw content body plus X-Fetch-* metadata.

Accepts only the five params the spec declares for this endpoint. custom (#2481) and the markdown_* / with_* tuning fields (#2539) are POST-body options with no GET query param — they were silently dropped by this builder, so they are now compile errors instead. Use create() (POST) for those.

The query string is built by iterating FETCH_GET_QUERY_KEYS, the same list FetchGetOpts is derived from, so every accepted option is necessarily serialized.

requestOptions carries the CLIENT-side abort budget (requestTimeoutMs) and an optional caller signal. As on create, the gateway's own ceiling for a fetch is 60 s, so a per-call budget is what keeps a slow upstream from holding the caller for the constructor default.

Options (FetchOpts)

• url (required) — string
• format — 'markdown' | 'html' — Output format. 'markdown' runs the HTML→markdown pipeline; 'html' returns raw HTML. Narrowed to the spec union — off-spec values (e.g. 'pdf') are rejected at compile time.
• country — string
• timeout_ms — number
• markdown_mode — 'article' | 'raw' | 'llm' — Markdown processing mode. Only used when format=markdown. article/raw/llm.
• markdown_query — string — BM25 query string for relevance-ranked filtering. Only used when format=markdown.
• markdown_links — 'inline' | 'references' | 'none' | 'text' — Link rendering style. Only used when format=markdown.
• markdown_images — 'inline' | 'references' | 'none' | 'text' — Image retention mode. Only used when format=markdown.
• with_links_summary — boolean — Append a Links: footer to the markdown output. Only used when format=markdown.
• with_images_summary — boolean — Append an Images: footer to the markdown output. Only used when format=markdown.
• markdown_compact — boolean — Compact whitespace output. Only used when format=markdown.
• markdown_filter_images — boolean — Filter low-signal images. Only used when format=markdown.
• markdown_include_media — boolean — When true, formats.links/formats.images return rich objects and a top-level tables array is included. Only used when format=markdown.
• markdown_include_warnings — boolean — When true, enables markdown-pipeline and tag-filter warnings for affected html/markdown requests.
• markdown_include_stats — boolean — When true, includes a top-level stats object (chars, tokens, blocks). Only used when format=markdown.
• cache_ttl — string | 0 — How long a freshly fetched URL may be served from cache. Matches the OpenAPI FetchRequest.cache_ttl schema: a duration string ("48h", "2d", up to 168h / 7d) or the integer 0 to disable caching. Defaults to "48h" server-side when omitted.
• custom — Record<string, unknown> — User-supplied JSON payload, base64-encoded into the X-Fetch-Custom response header so callers can correlate the response to caller-side state. Capped at 4096 UTF-8 bytes after JSON serialization. Does NOT affect cache-key inputs.