# OpenAPI specification
Where to find the machine-readable OpenAPI description of the API, what it is good for, and how to generate a client from it.
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 seven
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.
Where to find the machine-readable OpenAPI description of the API, what it is good for, and how to generate a client from it.
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.
There is no official SDK: 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.
Save the contract locally as pdfblocks.openapi.yaml, then point a code
generator at it. OpenAPI Generator covers the
most languages; this scaffolds a Python client:
Swap -g python for ruby, csharp, typescript-fetch, go, php, or any
other supported generator. Two common alternatives:
Swagger Codegenbash
# Multi-language generator, similar to OpenAPI Generator.swagger-codegen generate \ -i pdfblocks.openapi.yaml \ -l java \ -o ./pdfblocks-client
openapi-typescriptbash
# TypeScript types only (no runtime client): pairs well with fetch.npx openapi-typescript pdfblocks.openapi.yaml \ --output ./pdfblocks.d.ts
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 for the full
picture of supported integration surfaces.
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 seven
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 to
know which changes are backward-compatible and how breaking changes ship.
