OpenAPI and Postman

The whole public API is described as one OpenAPI 3.1 document. Tools read it to show every endpoint with its fields, to build a request collection in an API client such as Postman, or to generate a typed client for your language. It is the machine-readable twin of this reference, and it is written from the same code: the request bodies in it are the very JSON schemas the API validates requests with.

Where the spec is

curl https://api.castpdf.com/openapi.json --output castpdf-openapi.json

GET https://api.castpdf.com/openapi.json needs no API key and may be fetched from any website (it is served with access-control-allow-origin: *), so browser-based tools can load it directly. It is plain JSON, and it may be cached for a few minutes.

What it covers

• Paths: every route of /v1 that this reference documents, from POST /v1/pdf to the webhook delivery log, with path and query parameters, the Idempotency-Key header where it applies, request bodies and the main responses. A test in our codebase fails when a /v1 route is missing from the spec or the spec names a path that does not exist.
• Authentication: a bearer scheme (Authorization: Bearer YOUR_API_KEY); the signed download links are marked as needing no key.
• Schemas: the shared objects under components.schemas: Document, Batch, WebhookEndpoint, WebhookDelivery, TemplateSummary, Template, TemplateFields, TemplateTreeField, Team, Error (with every error code as an enum) and EInvoice, the e_invoice field with its EN 16931 business terms.
• Webhooks: the three events your endpoint receives, pdf.created, pdf.failed and batch.completed, under the top-level webhooks key, with their CastPDF-Signature, CastPDF-Event-Id and CastPDF-Event-Type headers. The webhooks guide explains how to verify them.

What it does not hold: the prose of these pages. Limits that depend on your plan, the retry schedules and the reasons behind an error are described here in the docs, so keep the reference open next to the generated code.

Postman and other API clients

CastPDF does not publish a ready-made Postman collection file. Postman builds one from the spec in a few clicks:

1. In Postman, choose Import, then Link.
2. Paste https://api.castpdf.com/openapi.json and confirm. Postman creates a collection with a request for every endpoint.
3. Set the collection's authorization to Bearer Token with your API key. Start with a test key: test PDFs are watermarked and never counted. See test and live mode.

Most other API clients, such as Insomnia, import an OpenAPI document the same way, from the URL or from the downloaded file. Importing again later picks up new endpoints and fields.

Generating a client

Any generator that understands OpenAPI 3.1 can turn the spec into a typed client. Two common choices, run against the downloaded file:

# TypeScript types for fetch-based code
npx openapi-typescript castpdf-openapi.json --output castpdf.d.ts

# A client for many languages (Python here), with the OpenAPI Generator
npx @openapitools/openapi-generator-cli generate -i castpdf-openapi.json -g python -o castpdf-client

For Node.js and Python, the official SDKs cover the same API (the Node.js types are generated from this description); for every other language, the generated code is yours to own. A few things the spec cannot express well, worth handling by hand:

• POST /v1/pdf answers with a PDF, an XML (for XRechnung) or JSON, depending on response and e_invoice. Read the content-type header before you parse the body.
• Requests that render can take up to 30 seconds; set the generated client's timeout to at least 60 seconds.
• Send an Idempotency-Key with POST /v1/pdf and POST /v1/batches when you retry, as described in idempotency.

Keeping in sync

The spec is served by the running API, its request bodies are the routes' own schemas, and a test keeps its paths in step with the routes, so it matches what is deployed: when the API changes, the spec changes with it. The changelog notes the changes worth knowing about. To stay current, regenerate your client or re-import into Postman from the same URL when you update your integration, and keep tolerant parsing: ignore response fields your code does not know, because new ones appear over time.