* * * API REFERENCE * * *

One endpoint.

POST a document, get its contents back. $0.75 per 1,000 pages, and your first 100 pages are free. Get a key from the dashboard — or try it with zero code on /runs.

01 / QUICKSTART

curl https://api.pennyocr.com/v1/ocr \
  -H "Authorization: Bearer $PENNYOCR_API_KEY" \
  -F "file=@receipt.jpg"

# $0.75 per 1,000 pages, first 100 free

02 / POST /v1/ocr

URL

https://api.pennyocr.com/v1/ocr

AUTH

Authorization: Bearer pk_live_… — mint keys on the dashboard. Keys are shown once and stored hashed.

BODY

multipart/form-data with a single file field. PDF, PNG, JPEG, WebP or TIFF. Up to 50 MB and 500 pages per request; multipage PDFs are billed per page.

?format=

markdown (default) — structured output: headings, HTML tables for tabular regions, reading order preserved. text — the same full transcription, stripped to plain text.

RESPONSE

{
  "id": "ocr_ab12cd34",
  "pages": 3,
  "text": "…full document (pages joined by \f)…",
  "page_results": [{ "page": 1, "text": "…" }],
  "cost_usd": 0.00225,
  "model": "nuextract3"
}

ERRORS

401 bad key · 402 free tier + credits exhausted (buy credits on the dashboard) · 413 too big · 422 unreadable file or bad format param · 429 slow down

03 / BILLING

PRICE

$0.75 per 1,000 pages ($0.00075/page), prepaid credits. Your first 100 pages are free.

CREDITS

Buy packs on the dashboard (10k / 100k / 1M pages). Credits never expire. Auto-reload can top you up from your saved card when you run low.

PRIVACY

PennyOCR does not store API documents or results by default. Flip “API result storage” on the dashboard if you want runs kept and browsable on /runs. Processing providers have separate retention rules described in our privacy policy.

03B / URL INPUT & COST GUARDS

POST /v1/ocr/url

JSON {url, format?, pages?, max_pages?, max_cost_usd?} — we fetch the document. Page ranges like 1-20,25. Caps refuse with a deterministic 413 carrying the exact numbers, before any processing.

POST /v1/estimate

JSON {url, pages?} → page count + exact cost. Free — nothing is OCR'd.

MCP SERVER

https://mcp.pennyocr.com — add it to mcpServers with your key in an Authorization header and agents get read_document + estimate_cost. Details: /mcp.

04 / OPENAI-COMPATIBLE

POST /v1/chat/completions

Drop-in OpenAI Chat Completions endpoint: send image_url content parts (data: or https URLs) with model pennyocr-markdown or pennyocr-text — works with any OpenAI SDK by changing base_url to https://api.pennyocr.com/v1. Billed per image, same price.

SPEC

OpenAPI: openapi.yaml · openapi.json. For agents: /llms.txt · /pricing.txt (signup, keys and payment, fully documented for non-humans).

05 / GET /health

URL

https://api.pennyocr.com/health — engine + model status, no auth.

Stuck, need higher limits, or want a batch endpoint? HELLO@PENNYOCR.COM — a human replies fast.