# 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.