/docs / quickstart

For agent developers

API quickstart

Five minutes from signup to a clean structured AIDocument response. One endpoint, one shape, every URL on the web.

Get an API key

Sign up at /signup. The free tier is 2,000 AIDocuments / month, no credit card. Your raw key shows once on the dashboard right after signup; copy it into your password manager. Mint additional keys (one per environment) at /dashboard/keys.

Set it as an env var

Treat keys like any other production secret. Do not commit them. The samples below read from $LYRENTH_KEY.

Resolve a URL with /v1/aidocument

POST a JSON body with the URL you want resolved. The response is the canonical AIDocument v2 shape. If we already have the page it is served from cache; if not, we fetch, clean, and save it once so the next agent gets it instantly too.

curl

curl -X POST https://api.lyrenth.com/v1/aidocument \
  -H "Authorization: Bearer $LYRENTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://en.wikipedia.org/wiki/Web_indexing"}'

python

import os, requests
KEY = os.environ["LYRENTH_KEY"]
r = requests.post(
    "https://api.lyrenth.com/v1/aidocument",
    json={"url": "https://en.wikipedia.org/wiki/Web_indexing"},
    headers={"Authorization": f"Bearer {KEY}"},
)
doc = r.json()
print(doc["identity"]["title"])
print(doc["signals"]["word_count"], "words")

node

const KEY = process.env.LYRENTH_KEY;
const r = await fetch("https://api.lyrenth.com/v1/aidocument", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://en.wikipedia.org/wiki/Web_indexing" }),
});
const doc = await r.json();
console.log(doc.identity.title, doc.signals.word_count + " words");

Read the response

Every successful 2xx call returns the same grouped envelope regardless of how the source page was rendered. The cache.status field tells you whether this call hit the shared index or triggered a fresh fetch.

{
  "schema":  { "name": "AIDocument", "version": "2.0" },
  "source":  { "url": "…/Web_indexing", "render_mode": "static", "status_code": 200 },
  "cache":   { "status": "hit", "origin_contacted": false },
  "identity": { "title": "Web indexing - Wikipedia", "language": "en" },
  "content":  { "markdown": "Web indexing or…" },
  "signals":  { "word_count": 1552, "reading_time": 7, "has_json_ld": true },
  "economics": {
    "raw_html_tokens_approx": 21331,
    "output_tokens_approx":   2715,
    "token_savings_percent":  0.873
  }
}

(Optional) Force a fresh fetch

Default is cache-first. To bypass the lookup and crawl now, set freshness_policy on the request body. Allowed values: cache_first (default) or force_refresh. A force_refresh uses 2 credits instead of 1, since it triggers a live crawl.

curl -X POST https://api.lyrenth.com/v1/aidocument \
  -H "Authorization: Bearer $LYRENTH_KEY" \
  -d '{ "url": "https://example.com/post", "freshness_policy": "force_refresh" }'

Beyond the basics

Other endpoints

/v1/aidocument handles 95% of what an agent needs; the rest is housekeeping.

POST/v1/aidocument

Resolve any URL

Cache on hit within your freshness window, fresh fetch on miss, body shared with every caller. Each success counts as one request. Optional max_tokens caps the returned markdown to a context budget.

POST/v1/aidocument/batch

Resolve up to 20 URLs

One call, an array of clean AIDocuments with per-URL error isolation (a failed URL does not block the others). Billed one credit per successfully-read URL.

GET/v1/document?url=…

Index lookup only

Returns the cached AIDocument if indexed, 404 otherwise. Never crawls. Counts as one request.

POST/v1/submit

Queue a URL for indexing

Returns 202; we crawl in the background. Free, does not count toward quota.

GET/v1/quota

Your usage state

This month's consumed-vs-limit shape. Free. The dashboard sidebar reads this same endpoint.

GET/v1/stats

Public counter

Live count of indexed documents. No auth, CORS-open. Useful for landing pages and embeds.

GET/aidocument.schema.json

Machine-readable contract

The full v2 envelope as JSON Schema (draft-07). Validate responses or generate types.

Errors

What can go wrong

Errors are typed JSON; pattern-match on the error field rather than the HTTP status alone.

HTTP 429rate_limited

Per-key monthly quota reached. Response includes a Retry-After header pointing at next month.

HTTP 502upstream_blocked

The target site's WAF / CDN rejected our crawler. Distinguish from generic upstream failures.

HTTP 404not_indexed

On /v1/document only. The URL is not in our cache. Hint suggests calling /v1/aidocument.

HTTP 401unauthorized

Missing or invalid Bearer token. Verify $LYRENTH_KEY is set and the key is not revoked.

Want the full document shape?

Every field in the response, and the contract guarantees we make about backward compatibility.

Read the AIDocument spec →Back to docs