# Endpoint reference

The complete, always-current endpoint reference is generated from the live API's OpenAPI specification:

- **[Open the interactive API reference →](https://docs.uninvoice.app/api/)**: every endpoint, parameter, request, and response, browsable and searchable (Redoc).
- **[Download the OpenAPI spec (JSON) →](https://docs.uninvoice.app/openapi.json)**: the raw specification, to import into Postman/Insomnia, generate a client, or drive your own tooling.

Because it is generated straight from the running backend, it never drifts from the real API. All paths are relative to the [base URL](https://docs.uninvoice.app/api/overview#base-url) and require a [Bearer token](https://docs.uninvoice.app/api/overview#authentication); amounts are in [cents](https://docs.uninvoice.app/api/overview#money) and field names are `snake_case`.

## A typical integration flow

1. **Create the recipient** with `POST /v1/entities` (or reuse an existing one from `GET /v1/entities`).
2. _(Optional)_ **Preview taxes** with `POST /v1/taxes/prefill`.
3. **Create the draft** with `POST /v1/invoices`.
4. **Issue it** with `POST /v1/invoices/{id}/issue`: this assigns the invoice number and, for Spanish issuers, reports it to the AEAT.
5. **Download the PDF** with `GET /v1/invoices/{id}/pdf`.

> **If you are established in Spain**
>
> Issuing is blocked until your Veri\*Factu authorization is **in effect**: a signed authorization document that has passed our checks (the standard way), or a power of attorney granted at the AEAT **and confirmed by it** (checked once a day: confirming the grant in the app does not lift the gate on its own). Until then the invoice stays a draft and `issue` returns `403` with `error: "verifactu_authorization_required"`. See the [Veri\*Factu guide](https://docs.uninvoice.app/verifactu/overview).

AI-driven mutations are held for approval

A mutating request made with an API token that does **not** present a valid `X-Human-Proof` header is not executed: it is recorded for human review and returns `202 pending_approval`. A human then approves (replays) or rejects it. See the [AI Audit guide](https://docs.uninvoice.app/api/ai-audit).