# pdf-text

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

Bot-alone path: this file → get key → quote → free-try `POST /pdf`. 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`). GET `/incidents` is public status (not an install entry). Issue a caller key at POST /keys (`ssm_…` 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=pdf`
5. POST `/pdf` `{ "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" }`
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://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf","pages":1,"text":"Dummy PDF file","credits_burned":1,"credits_remaining":0}
```

Fail extract (`ok:false`, no debit): compare `ok`; HTTP 200 means runner finished.

## Fail shapes

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

Checkout is intent-only until confirm. Debit reason on success is `pdf_success`. No OCR (see image-ocr).

MCP: `POST /mcp` (not an install entry). Discovery: `GET /.well-known/mcp.json`. Snippet: `GET /mcp.json` (this file only advertised pointer). Tools include `pdf_extract` plus key/credit tools. Env `PDF_TEXT_API_KEY`.