# OpenAPI specification Get the machine-readable OpenAPI 3.0.0 contract (currently 1.18.0) and generate a typed client with common codegen tools. The PDF Blocks API is described by a single OpenAPI document — the machine-readable contract that these docs are written against. It is **OpenAPI 3.0.0**, currently version `1.18.0`, published as `pdfblocks.openapi.yaml`. Every route, parameter, enum, constraint, and response in the API is defined there, so you can generate a typed client, validate requests before they leave your process, or stand up a mock server. <Note> There is [no official SDK](/docs/api/libraries-and-integrations) — raw HTTP is the first-class path, and code generation from this spec is the supported way to get a typed client. A hosted download URL is on the way; in the meantime, request the current `pdfblocks.openapi.yaml` from [support@pdfblocks.com](mailto:support@pdfblocks.com). </Note> ## What the spec is good for - **Typed clients.** Generate models and request methods in your language instead of hand-writing multipart calls. - **Validation.** Check requests and responses against the schema in tests or at the edge of your service. - **Mocking.** Feed the document to a mock server to develop against before wiring up real calls. - **Editor support.** Load it into an OpenAPI-aware editor for autocompletion and inline docs. ## Generate a typed client Save the contract locally as `pdfblocks.openapi.yaml`, then point a code generator at it. [OpenAPI Generator](https://openapi-generator.tech) covers the most languages; this scaffolds a Python client: ```bash title="openapi-generator" npm install -g @openapitools/openapi-generator-cli openapi-generator-cli generate \ -i pdfblocks.openapi.yaml \ -g python \ -o ./pdfblocks-client ``` Swap `-g python` for `ruby`, `csharp`, `typescript-fetch`, `go`, `php`, or any other supported generator. Two common alternatives: <CodeGroup> ```bash title="Swagger Codegen" # Multi-language generator, similar to OpenAPI Generator. swagger-codegen generate \ -i pdfblocks.openapi.yaml \ -l java \ -o ./pdfblocks-client ``` ```bash title="openapi-typescript" # TypeScript types only (no runtime client) — pairs well with fetch. npx openapi-typescript pdfblocks.openapi.yaml \ --output ./pdfblocks.d.ts ``` </CodeGroup> Whichever tool you use, configure the generated client with the base URL `https://api.pdfblocks.com` and send your key in the `X-API-Key` header. See [Libraries and integrations](/docs/api/libraries-and-integrations) for the full picture of supported integration surfaces. ## Spec vs. docs The spec is machine truth; these docs are human truth. The OpenAPI document gives you the exact shape of every request and response. The prose docs add what a schema can't: *why* and *when* to use an action, worked examples in five languages, the watermark template catalog, and error recovery. Use both — the spec to generate and validate, the docs to understand. Client code is generated against a specific version. Before pinning a generated client, read [Versioning and stability](/docs/api/versioning-and-stability) to know which changes are backward-compatible and how breaking changes ship.