* * * API REFERENCE * * *

One endpoint.

POST a document, get its contents back. $0.75 per 1,000 pages, first 100 pages free every month. 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. First 100 pages each month 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

Zero retention by default: API documents and results are processed and discarded. Flip “API result storage” on the dashboard if you want runs kept and browsable on /runs.

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.