# LeanCrawl

> API-first web data for AI agents: capture pages as markdown/html/links/screenshot/pdf,
> crawl sites asynchronously, monitor pages for changes.
> Base URL: https://api.leancrawl.com — Auth: `Authorization: Bearer ac-…`
> (create keys in the dashboard → API Keys).

## Reference

- [API documentation](https://leancrawl.com/docs): Guides, API reference, notifications, FAQ
- [llms-full.txt](https://leancrawl.com/llms-full.txt): all docs pages in one file
- [OpenAPI 3.1 spec](https://api.leancrawl.com/openapi.json): machine-readable full contract
- [SKILL.md](https://leancrawl.com/SKILL.md): agent self-onboarding doc
- [MCP server](https://leancrawl.com/mcp): 26 tools over Streamable HTTP —
  `claude mcp add --transport http leancrawl https://leancrawl.com/mcp -H "Authorization: Bearer ac-…"`

## Endpoints (credits per call)

- markdown 1 — clean Markdown for LLM consumption
- html 1 — fully rendered markup
- links 1 — all links on one page
- map 1 — site URL discovery (does NOT fetch pages)
- screenshot 2 — PNG/JPEG/WebP artifact (Bearer-auth URL in response)
- pdf 2 — PDF artifact (Bearer-auth URL in response)
- extract 3 — AI structured extraction (schema or prompt required)
- crawl — POST /v1/crawl → 202, poll GET /v1/crawl/{id}?include=pages; 1 credit/page, reserved up-front as limit
- monitor — POST /v1/monitor periodic change detection; 1 credit per check; GET /v1/monitor/{id}/checks/{checkId}/diff for adjacent-snapshot line diffs (free); GET /v1/monitor/{id}/snapshots/{snapshotId} for the normalized markdown source (free, ~10 snapshots kept)
- account — GET /v1/account/usage (balance/quota/reserved), /v1/account/usage/daily + /v1/account/activity (per-key spend via `?api_key_id=`/`self`), /v1/account/keys (`credits_30d` per key) — free

## Protocol essentials

- Envelope: sync `{success:true, data, meta?, credit_cost}` (`meta` = page metadata `{title?, status_code, url, duration_ms}` on capture endpoints) · async `{success:true, job_id, status_url}` (HTTP 202) · error `{success:false, error:{code,message}}`
- Error codes: INVALID_REQUEST 400 · UNAUTHORIZED 401 · INSUFFICIENT_CREDITS 402 · FORBIDDEN 403 · JOB_NOT_FOUND/NOT_FOUND 404 · TARGET_TIMEOUT 408 · RATE_LIMITED 429 (+Retry-After) · TARGET_BLOCKED 403 · TARGET_UNREACHABLE/PROVIDER_ERROR 502 · INTERNAL_ERROR 500
- Failed runs bill 0 credits; cached hits still cost the endpoint price
- Pagination: `?cursor` + `?limit` keyset; `next_cursor`/`next` null = end of results
- Webhook signature: `X-LeanCrawl-Signature: t=<unix_s>,v1=<hmac-sha256-hex(secret, "<t>.<rawBody>")>` — verify the RAW request body (never re-serialize); ±300s replay window; retries at 60/300/900s

## Optional

- [Playground](https://leancrawl.com/playground): zero-config logged-in trial
- [Pricing](https://leancrawl.com/pricing)