● reader.hilgard.cz

API reference

POST /v1/read

One page as Markdown or HTML. Base URL https://reader.hilgard.cz (also served on serp.hilgard.cz with the same key). Requests are JSON over HTTPS; every call takes Authorization: Bearer YOUR_API_KEY. Get a key with 5,000 free pages.

Request

curl -X POST https://reader.hilgard.cz/v1/read \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "format": "markdown",
    "only_main_content": true
  }'
urlstring, requiredA public http or https URL, ports 80 and 443, at most 2,048 characters. Private and internal addresses are refused, after redirects too.
format"markdown" (default) | "html"Markdown with GFM tables and absolute links, or HTML without scripts and styles.
only_main_contentboolean, default trueRemove navigation, headers, footers, cookie bars and link farms. false returns the whole rendered page.
include_linksboolean, default trueKeep links; false gives prose only, a noticeable token saving on link-heavy pages.
max_lengthinteger 1000–5000000, default 5000000Characters returned per call. By default the whole document comes in one answer; set it only when you want slices, e.g. to fit an LLM context.
start_indexinteger, default 0Offset of a slice: send next_index of the previous answer.

GET works the same with a query string, handy for quick tests: GET /v1/read?url=https%3A%2F%2Fexample.com&format=html.

Response

{
  "url": "https://example.com/pricing",
  "final_url": "https://example.com/pricing",
  "status": 200,
  "title": "Pricing",
  "format": "markdown",
  "content": "# Pricing\n\n| Plan | Price |\n| --- | --- |\n| Pro | $20 |",
  "length": 52,
  "total_length": 52,
  "truncated": false,
  "next_index": null,
  "fetch": { "mode": "http", "challenge": null, "from_cache": false, "ms": 1180 },
  "billed": true
}
urlThe URL you asked for.
final_urlThe URL after redirects.
statusHTTP status of the page as served.
titleThe page title.
format"markdown" or "html", as asked.
contentThe page as Markdown or HTML (this slice).
lengthCharacters in content.
total_lengthCharacters in the whole document.
truncatedtrue when more of the document follows.
next_indexstart_index of the next slice, or null.
fetch.mode"http" (a plain request was enough), "browser" (JavaScript had to run) or "challenge" (a bot check was passed).
fetch.challenge"cloudflare", "datadome" or null.
fetch.from_cachetrue when the document came from the cache (read within the last 15 minutes).
fetch.msTime the read took on our side.
billedWhether this call was billed (a further slice of a cached document is not).

Just the document

Send Accept: text/markdown (format markdown) or Accept: text/html (format html) and the body is the bare document. The metadata comes in headers: X-Read-Final-URL, X-Read-Status, X-Read-Total-Length, X-Read-Truncated, X-Read-Next-Index, X-Read-Fetch-Mode and X-Read-Challenge.

curl "https://reader.hilgard.cz/v1/read?url=https://example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/markdown" > page.md

Long documents

By default you get the whole document in one answer, up to 5,000,000 characters. Want it in parts, for example to fit an LLM context? Set max_length. When truncated is true, call again with start_index set to next_index. The whole document stays cached for 15 minutes, so further slices are fast and not billed (billed: false, X-Billed-As: none).

How a page is read

A plain request through our own mobile exits comes first; on most sites behind Akamai or PerimeterX that is already enough. An unrendered JavaScript shell goes to a headless browser. A Cloudflare or DataDome check is retried on another exit, then passed in a real Chrome (about 10–25 s). You do not choose; fetch.mode tells you what happened, and the price is the same either way. Allow up to 180 s per call in your HTTP client.

Billing

$0.50 per 1,000 delivered pages, whatever the page needed. New accounts get 5,000 free pages, counted apart from the free searches of the SERP API. Paid usage of both comes out of one prepaid credit in your account, which never expires. Only a delivered page (HTTP 200) is billed; every error below is free. Every response carries X-Quota-Limit / X-Quota-Remaining (free pages), X-Balance-USD and X-Billed-As; GET /v1/usage shows the totals under read.

Limits

PlanReads / minuteAt oncePer day
Free1021,000
Paid (default, custom per customer)6010—

The limits are a starting point for testing; in paid use they are set for each customer by agreement.

Errors

Errors are JSON { "error": "…", "message": "…" }. None of them is billed.

400bad_requestInvalid parameters, or a URL that is not a public http(s) address.
401unauthorizedMissing or invalid API key.
402quota_exceededFree pages and credit used up.
422target_errorThe page answered with an error (target_status says which, e.g. 404).
422target_unreachableThe host does not resolve or did not answer.
429rate_limited / daily_limit / busyA limit of your key, or all reader capacity in use; see Retry-After.
502blockedThe page could not be read past its bot protection this time; retry later.
502empty_pageThe page came back without content (a wall that answered 200, or a page that did not render).
504timeoutThe page took too long to load.

What may be read

Public web pages. The reader never logs in, and it must not be used for personal data or content behind a login; you are responsible for respecting the terms of the sites you read. See the terms of use.