API ReferenceFetch

Fetch a URL (POST)

Same as GET /v1/fetch but with a JSON request body. The response is the same, including the X-Fetch-Fast-Path rule for what the body holds: the upstream bytes verbatim when it is true, the rendered page when it is false.

Limits: request bodies are capped at 512 KB. An oversized body returns a 400 with error code request_too_large.

For AI agents: https://bytekit.com/llms.txt — every docs page is available as markdown by appending .md

POST
/v1/fetch

Authorization

AuthorizationRequiredBearer <token>

API key. Manage keys from the dashboard at app.bytekit.com.

In: header

Request Body

application/jsonRequired
urlRequiredstring
Format: "uri"
countrystring

Two-letter country code. Either case is accepted; the value is upper-cased.

Default: "US"Pattern: "^[A-Za-z]{2}$"
timeout_msinteger
Default: 60000Minimum: 1000Maximum: 90000
cache_ttlstring | integer

How long a freshly fetched URL may be served from cache. 0 skips the cache read; cache-eligible fresh results are still written with the default 7-day TTL so later non-zero-TTL callers can HIT. Safety-classified WAF husks remain live-only and are not written. Accepts Nh (hours, up to 168h), Nd (days, up to 7d), or the integer 0. Examples: 0, 48h, 2d. Invalid values receive a 422 validation_error with an actionable message.

Default: "48h"
customobject

User-supplied JSON payload, base64-encoded into the X-Fetch-Custom response header so callers can correlate the response back to caller-side state (job IDs, batch metadata, etc.). Capped at 4096 UTF-8 bytes after JSON serialization. Does NOT affect cache-key inputs — two requests differing only in custom share the same cache slot.

Default: {}
curl -X POST https://api.bytekit.com/v1/fetch \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com"
}'

Content from upstream.

"string"

GET /v1/fetchFetch a URL (GET)

Direct HTTP fetch. Metadata is returned in X-Fetch-* headers. What the body holds depends on `X-Fetch-Fast-Path`. When it is `true`, a successful response returns the upstream response bytes verbatim. When it is `false` the request fell back to a browser render, and the body is the rendered page rather than the bytes the target sent; `X-Fetch-Content-Length` is then the compressed size of that page. Non-2xx upstream responses use the `upstream_error` JSON envelope with the upstream HTTP status.

Fetch Bulk

Fetch Bulk API — endpoints, requests, and responses.