# API reference

Document Recognition API — every endpoint, parameter and response, generated from `openapi.yaml`,
which is the contract this service is built from and validated against.

The base URL is `https://api.doc.cheap`, the one host the contract's `servers` block
names. Every endpoint takes and returns `application/json`, and every call is
authenticated with `Authorization: Bearer <api key>` — `sk_live_…` for an account, or the
public `sk_sandbox_public` for trying the API without registering.

Recognition is synchronous. `POST /v1/scans` runs the engine while the request is open and
returns the extracted data in the same response, so there is no job to poll and no webhook
to register. There is one response shape, the same for every scan and every caller:
eight groups under a `meta.schema_version` of `1.0`, with nothing to negotiate and no
header or option that selects a different body.

Every failure carries one body — a stable `code`, a human `message`, a `docs_url` pointing
at that code's own page, a `request_id` and an `event_id` that is non-null only for a
failure the service recorded against itself.

The interactive reference below renders the whole contract and runs calls from the page.
Each endpoint also has a plain page that needs no JavaScript:

- [Create a scan](/reference/endpoints/create-a-scan) — `POST /v1/scans`
- [Retrieve a scan](/reference/endpoints/retrieve-a-scan) — `GET /v1/scans/{id}`
- [Get usage](/reference/endpoints/get-usage) — `GET /v1/usage`

The contract itself is at [`/openapi.yaml`](/openapi.yaml), and the pages that
state it in prose are the [reference section](/reference).