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
}'| url | string, required | A 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_content | boolean, default true | Remove navigation, headers, footers, cookie bars and link farms. false returns the whole rendered page. |
| include_links | boolean, default true | Keep links; false gives prose only, a noticeable token saving on link-heavy pages. |
| max_length | integer 1000–5000000, default 5000000 | Characters 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_index | integer, default 0 | Offset 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
}| url | The URL you asked for. |
| final_url | The URL after redirects. |
| status | HTTP status of the page as served. |
| title | The page title. |
| format | "markdown" or "html", as asked. |
| content | The page as Markdown or HTML (this slice). |
| length | Characters in content. |
| total_length | Characters in the whole document. |
| truncated | true when more of the document follows. |
| next_index | start_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_cache | true when the document came from the cache (read within the last 15 minutes). |
| fetch.ms | Time the read took on our side. |
| billed | Whether 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
| Plan | Reads / minute | At once | Per day |
|---|---|---|---|
| Free | 10 | 2 | 1,000 |
| Paid (default, custom per customer) | 60 | 10 | — |
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.
| 400 | bad_request | Invalid parameters, or a URL that is not a public http(s) address. |
| 401 | unauthorized | Missing or invalid API key. |
| 402 | quota_exceeded | Free pages and credit used up. |
| 422 | target_error | The page answered with an error (target_status says which, e.g. 404). |
| 422 | target_unreachable | The host does not resolve or did not answer. |
| 429 | rate_limited / daily_limit / busy | A limit of your key, or all reader capacity in use; see Retry-After. |
| 502 | blocked | The page could not be read past its bot protection this time; retry later. |
| 502 | empty_page | The page came back without content (a wall that answered 200, or a page that did not render). |
| 504 | timeout | The 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.