Endpoints

The full InvoicePDF API surface: generate an invoice or receipt, check liveness, and fetch the JSON Schemas.

Base path is versioned: /v1. Breaking changes go to /v2; additive fields never bump the version. The version is also echoed in the X-InvoicePDF-Version response header.

Method	Path	Purpose	Response
POST	/v1/invoice	Generate an invoice PDF from JSON	`application/pdf` (200) or error JSON
POST	/v1/receipt	Generate a receipt variant (same schema, `docType: "receipt"`)	`application/pdf` (200) or error JSON
GET	/v1/health	Liveness check	`{"status":"ok","version":"1.0.0"}`
GET	/v1/schema/invoice.v1	The request JSON Schema	`application/schema+json`
GET	/v1/schema/error.v1	The error envelope schema	`application/schema+json`

POST /v1/invoice

Request body is Content-Type: application/json, UTF-8, a single Invoice object — see Invoice Schema. Maximum body size is 256 KB.

Success response headers:

text

Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-<number>.pdf"
X-InvoicePDF-Version: 1.0.0
X-Request-Id: <uuid-v7>
X-Quota-Remaining: <n>        # when known

By default the response body is the PDF, byte for byte. Add ?format=json — or send Accept: application/json — to get the same bytes back base64-encoded in a JSON envelope instead. See Response Formats.

POST /v1/receipt

Same handler and same request schema as /v1/invoice, with docType preset to "receipt". A receipt omits the invoice title and some B2B fields but reuses the same layout — one code path, no drift between the two document types.

GET /v1/health

Liveness probe. No authentication required.

bash

curl https://invoicepdf.annave.tech/v1/health
# {"status":"ok","version":"1.0.0"}

GET /v1/schema/invoice.v1

Returns the JSON Schema (draft-07) that request bodies to /v1/invoice and /v1/receipt are validated against. Point an editor or code generator at it for autocomplete and validation before a request is ever sent.

bash

curl https://invoicepdf.annave.tech/v1/schema/invoice.v1

GET /v1/schema/error.v1

Returns the JSON Schema for the error envelope shape — see Error Codes.

bash

curl https://invoicepdf.annave.tech/v1/schema/error.v1

Idempotency: send an Idempotency-Key header on POST /v1/invoice or POST /v1/receipt to make a retried request safe — a repeated key within 24h returns the original result instead of being counted twice against quota.