# Clearcrawl

> Pay-per-call API for AI agents. It turns any URL into clean markdown/JSON, and converts PDF, XLSX/CSV and DOCX files into text and tables. You get a free tier with no signup, then prepaid credits.

Base URL: https://agentreader.onrender.com
(It runs on a free host, so the first request after it has been idle can take about a minute.)

## REST endpoints
- POST /v1/read  JSON {"url": "...", "format": "json"|"markdown"} -> {title, byline, published, markdown, text, links[], tables[]}
  GET form: /v1/read?url=...&format=markdown
- POST /v1/convert  multipart field "file", or JSON {"url": "..."}, or {"base64": "...", "filename": "x.pdf"}
  -> PDF: {pages, page_text[], markdown}; XLSX/CSV: {sheets[{name, rows, records}], markdown}; DOCX: {markdown, tables}
- GET /v1/pricing, GET /health

## MCP (remote, Streamable HTTP)
- URL: https://agentreader.onrender.com/v1/mcp (alias: /mcp)  (stateless; POST only; header "Authorization: Bearer <key>" is optional)
- Tools: read_url(url, format?), convert_file(url? | base64 + filename?)

## Pricing (1 credit = $0.001)
- read: 2 credits per URL. convert: 3 credits per page or sheet. A PDF given to /v1/read is billed as convert.
- Free: 100 calls/day per IP with no key. After that the API returns HTTP 402 with a link to buy credits.
- Packs: ar_pack_5 = $5 for 5,000 credits; ar_pack_20 = $20 for 22,000; ar_pack_50 = $50 for 60,000.

## Buying credits
1. POST /v1/credits/checkout {"pack": "ar_pack_5"} -> {checkout_url}. A human or payment-capable agent opens checkout_url and pays.
2. Stripe redirects to /v1/credits/success, which shows the API key (once). Send JSON Accept to get {api_key, credits}.
3. Send "Authorization: Bearer <key>" on every call. Each response includes credits_remaining. GET /v1/credits/balance shows the balance.
4. Top up: POST /v1/credits/checkout with your key in Authorization adds credits to the same key.

## Limits
Max file 15 MB. Public http(s) URLs only. No JavaScript rendering or OCR yet.