Reference¶
This section states what the API does, exactly. It describes and does not instruct: the task-shaped pages are the guides, and the reasons behind a behaviour are in concepts.
Every page here is either generated from the contract or checked against the
release named in its footer. The base URL is https://api.doc.cheap, the one
host the contract's servers block declares.
The contract itself¶
| Page | What it states |
|---|---|
| API reference | The whole of openapi.yaml, rendered in the browser |
| POST /v1/scans | Request fields, headers, every response status and the codes it can answer with |
| GET /v1/scans/{id} | The path parameter, the stored result and when it is gone |
| GET /v1/usage | The balance and the counters for the current period |
These four are rendered from openapi.yaml at build time. The contract is the
source. The schemas and the routes produce it, and the pages are produced from
it, so neither can drift from the running service.
The result¶
| Page | What it states |
|---|---|
| The response | The eight groups, every key, its type, and when it is null |
| Field catalogue | Every field key the result publishes, with its label and category |
| Field languages and scripts | The 418 assigned language identifiers a reading can carry |
| MRZ reference | The zone as it is published, and how its check digits are reported |
| Result images | The seven crops, their height caps and what the re-encode does |
The rules of the interface¶
| Page | What it states |
|---|---|
| Scan options | The six options, their defaults and their ranges |
| Errors | All 21 codes, including the three no public call can raise |
| Limits | Every ceiling a caller meets, and the code each one answers with |
| HTTP status codes | Which codes share a status, and what separates them |
| Idempotency | What makes two requests the same request |
| Versioning | What counts as a breaking change, and what does not |
| Service levels | What the published indicators measure |
| Glossary | The words this documentation uses with a precise meaning |
What is generated and what is written¶
The error pages are the clearest case. Their set comes from the ErrorCode
enum in the contract, not from a list beside it. A code with no page fails the
build, and a page whose name is not a code fails it too. All 21 codes therefore have a
page, including the three raised only on internal surfaces. A docs_url that
answers 404 is worse than a short page.
The language table is generated the same way, from the 418 identifiers the recognition engine can report. Both are rebuilt on every commit, so a number on a page here is the number in the code.