Response formats

The format field controls how /fetch returns the response. It defaults to json.

json (default)

Structured metadata and response data. The body is a JSON object with the destination's status code, filtered response headers, the parsed body, and the final URL.

{
  "statusCode": 200,
  "headers": { "content-type": ["application/json"], "content-length": ["123"] },
  "data": { "message": "Hello World" },
  "finalUrl": "https://httpbin.org/json"
}

The destination's ETag and Last-Modified values remain in headers and are mirrored on the API response as x-origin-etag and x-origin-last-modified. See Conditional revalidation.

raw

The original response bytes, with upstream headers forwarded where possible. The body is always gzip-compressed (Content-Encoding: gzip), and the original destination status code is returned in the x-status-code header. Destination validators use the representation-safe x-origin-etag and x-origin-last-modified headers.

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://httpbin.org/html", "format": "raw" }'

markdown

HTML responses are converted to Markdown. The default markdownMode: "full" converts the cleaned page body in document order, including navigation, sidebars, and footers. Set markdownMode: "readable" to remove boilerplate and reduce output size when completeness matters less. Both modes preserve headings, lists, links, tables, code blocks, and inline formatting. Relative URLs are rewritten against the request URL's origin.

Set mainContentOnly: true to remove page chrome explicitly. The two options compose: full with mainContentOnly converts all remaining main content without Readability distillation.

Any structured data embedded in the page is preserved as fenced JSON code blocks, since it often carries the page's underlying data. Non-HTML responses are returned verbatim as text. The body is sent with Content-Type: text/markdown; charset=utf-8.

The original status and validators use x-status-code, x-origin-etag, and x-origin-last-modified. They describe the destination response, not the converted Markdown representation.

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "format": "markdown",
    "markdownMode": "readable"
  }'

Large pages

Markdown conversion takes at most 1 MiB of HTML, measured once scripts, styles and other non-content elements are removed. A page over that limit comes back as its original HTML, still sent as Content-Type: text/markdown, with no header or field to say so. The same applies to data in a browser actions response with format: "markdown", and inlined iframes count toward the limit.

mainContentOnly: true and markdownMode: "readable" remove more of the page before the limit is measured, so they can bring a large page under it. jsonSchema extraction measures the page the same way, without those two options, and falls back with body_too_large when the page is over the limit.

Final URL

When the destination redirects, the content you receive comes from a different URL than the one you requested, such as a search URL that resolves to a product page. Every format reports that URL in the x-final-url response header. If the request didn't redirect, the header carries the URL you requested. Every JSON body also carries the same value as finalUrl.

{
  "statusCode": 200,
  "headers": { "content-type": ["text/html; charset=utf-8"] },
  "data": "<!doctype html>...",
  "finalUrl": "https://shop.example.com/products/123"
}

Every /fetch response sends x-final-url, and every JSON body includes finalUrl with the same value. Error responses are included, such as a 400, 401 or 429. The only exception is a request body without a valid url: there is no URL to report, so both are left out. In raw responses, a destination's own x-final-url header is not forwarded, so the header always describes the request you made.