# image-ocr

> Machine-buyable image URL → plain text (OCR) for other AI bots. Live host `https://ocr.kymac.co`.
> **Sole advertised entry:** this file (`GET /llms.txt`). Do not start at OpenAPI, MCP, or `/`.
> Registry id: `co.kymac.ocr/image-ocr`. Capability keywords: image ocr, ocr text, vision text.

Bot-alone path: this file → get key → quote → free-try `POST /ocr`. No human mid-loop. Prepaid checkout only after the free credit is spent; intent-only until confirm. Rotate/revoke via `POST /keys/rotate` or `POST /keys/revoke`.

GET /health is public (`billing`, `runner_ready` — Tesseract ready). GET `/incidents` is public status (not an install entry). Issue a caller key at POST /keys (`ocr_…` shown once). First issue grants 1 free credit. Prefer `Authorization: Bearer`.

Install sequence:

1. GET `/llms.txt` (sole entry)
2. POST `/keys` — secret once; first issue = 1 free credit
3. `Authorization: Bearer …` (`X-API-Key` alias)
4. GET `/credits/quote?op=ocr`
5. POST `/ocr` `{ "url": "https://placehold.co/600x160/000000/FFFFFF/png?text=HELLO+OCR" }`
6. packs → checkout (`credits_pending`) → confirm (`credits_added`)
7. balance / events
8. rotate or revoke

## Golden proof

Pass (`ok:true`, burns 1):

```
{"ok":true,"url":"https://placehold.co/600x160/000000/FFFFFF/png?text=HELLO+OCR","text":"HELLO OCR","credits_burned":1,"credits_remaining":0,"pages":1,"width":600,"height":160}
```

HTTP 200 always means the runner finished when applicable — read `ok`. Fail closed paths do not debit.

## Fail shapes

Every fail body has `code`, `message`, `retryable`, `next`, and `error`. `next`: `refresh key` / `buy credits` / `retry` / `fix request`.

401: `missing_api_key` / `invalid_api_key` → `next=refresh key`
402: `insufficient_credits` → `next=buy credits`
400: `invalid_request` / fetch/image errors → `next=fix request`

Checkout is intent-only until confirm (`credits_pending` ≠ owned).

MCP: `POST /mcp` (not an install entry). Discovery: `GET /.well-known/mcp.json`. Registry auth: `GET /.well-known/mcp-registry-auth` (text/plain public key). Snippet: `GET /mcp.json` (this file is the only advertised pointer). Tools include `ocr_extract` plus key/credit tools. Gated tools prefer Bearer or env `IMAGE_OCR_API_KEY`.