API reference

Resolve one URL into an AIDocument

The main endpoint. Serves the stored copy when the page is in the index and inside your plan's freshness window, and fetches, cleans and stores it once when it is not, so the next agent to ask gets the fast path. The response is the v2 envelope documented on the AIDocument page. Request bodies are capped at 4 KB.

Responses

200 the AIDocument v2 envelope. 202 with {"status":"indexing"} and a Retry-After header when the page is not in the index and the live-fetch budget is full; the URL is queued and a retry in a few seconds normally lands. A served copy that was older than the freshness window carries the header X-Lyrenth-Stale: 1.

Resolve up to 20 URLs in one call

The same read, fanned out. Every URL is isolated: one that fails is reported in its own result and never blocks the others, so the call itself succeeds with a 200 as long as the request was well formed. Billed one credit per successfully-read URL. Request bodies are capped at 16 KB.

{
  "urls": [
    "https://example.com/a",
    "https://example.com/b"
  ],
  "freshness_policy": "cache_first",
  "max_tokens": 4000
}

{
  "results": [
    { "url": "https://example.com/a", "ok": true,  "document": { /* AIDocument v2 */ } },
    { "url": "https://example.com/b", "ok": false, "status": "upstream_not_found",
      "error": "origin returned 404",
      "message": "example.com returned 404 for that path. The page may have moved or never existed.",
      "upstream_status": 404, "host": "example.com" }
  ]
}

Each result carries url and ok. A successful one adds document. A failed one adds error, a named status, and, since September 2026, message: the same plain-English explanation a single read returns, plus upstream_status and host when an origin actually answered. Show the message to a person; branch on the status in code.

The status is the specific reason, not a generic one: upstream_forbidden, upstream_bot_filtered, upstream_blocked, upstream_not_found, upstream_gone, upstream_rate_limited, upstream_unavailable_legal, upstream_server_error, upstream_error, taken_down, robots_disallowed, no_content, indexing, or one of the transport codes listed further down. Before September 2026 every origin failure reported upstream_error, so treat an unknown status as a failure you cannot retry blindly.

The same read, as Markdown

One GET, no body, no JSON parsing. The response is text/markdown: a title, the page description, a source line, then the cleaned body. Made for a shell one-liner and for agents that want text rather than structure. Errors are still JSON, so check the content type or the status before treating the body as Markdown.

# Web indexing

> An overview of how search systems index the web.

Source: https://en.wikipedia.org/wiki/Web_indexing

---

Web indexing or...

Queue a URL for background indexing

Send {"url":"..."}. The URL enters the crawl queue ahead of pages we discovered ourselves, and the call returns immediately with 202. Once it lands, reads serve it from the index at cache speed; a read made before then simply fetches the page live, so there is no need to wait before asking. queued is false when the URL is already indexed or already waiting, which means your intent is satisfied and no new work was created.

{
  "status": "accepted",
  "url": "https://example.com/post",
  "queued": true,
  "note": "queued for background indexing; once it lands, reads serve it from the index"
}

Your plan and remaining credits

Takes no parameters. Reading it is what rolls your balance over at the start of a new month, so a call on the first of the month returns the fresh figure. Accounts on an unlimited plan get "unlimited": true instead of the counters.

{
  "unlimited": false,
  "tier": "free",
  "used": 143,
  "limit": 2000,
  "remaining": 1857,
  "period_start": "2026-08-01T00:00:00Z",
  "resets_at": "2026-09-01T00:00:00Z"
}