# Versioning and stability
How PDF Blocks versions the API with SemVer, what counts as a backward-compatible change, and how to pin to the v1 major with confidence.
PDF Blocks versions the API so you can adopt improvements without fear of
surprise breakage. The rules below tell you exactly which changes are safe to
receive automatically and how any breaking change would reach you.
## Semantic Versioning
The API follows [Semantic Versioning 2.0.0](https://semver.org). Given a version
number `X.Y.Z`:
| Part | Name | Meaning |
| ---- | ----- | ---------------------------------- |
| `X` | Major | Backward-incompatible changes. |
| `Y` | Minor | Backward-compatible feature adds. |
| `Z` | Patch | Backward-compatible bug fixes. |
The current spec version is `1.18.0`. You can always read the live version from
the `info.version` field of the
[OpenAPI specification](/docs/api/openapi-specification).
## The `v1` major in the path
The **major** version is pinned in the URL path: every action lives under `/v1/`,
as in `https://api.pdfblocks.com/v1/add_text_watermark`. Minor and patch releases
ship in place under `/v1/` — you receive them automatically and never change your
URLs to get them. Because breaking changes only ever ship under a new major (a
new path segment), staying on `/v1/` means staying on a stable contract.
## What counts as backward-compatible
Within `v1`, we make additive changes without a new major version. Treat all of
the following as things that can appear at any time, and write clients that
tolerate them:
- **New optional parameters** on an existing action.
- **New accepted values** for an existing parameter — a widened or expanded enum.
- **Parameter aliases** — a new name for an existing field, with the old name
still accepted.
- **Richer responses** — new fields in a response body or new response headers.
- **New actions and new endpoints.**
None of these require you to pin a minor version or change your code. To stay
compatible, ignore response fields you don't recognize rather than failing on
them, and don't assume a fixed, exhaustive set of enum values.
## How breaking changes ship
A breaking change — removing or renaming a required parameter, changing a
response in an incompatible way, or altering established behavior — would only
ever ship as a **new major version under a new path**, such as `/v2/`. Your
existing `/v1/` calls keep working unchanged, and you migrate on your own
schedule. We do not make breaking changes in place under `/v1/`.
## Pin to a major
Pin your integration to the `v1` major by keeping `/v1/` in your request URLs.
That is all the pinning you need: you automatically receive backward-compatible
minor and patch improvements, while breaking changes stay out of your path until
you choose to adopt a future major.
Track what changed in each release in the [Changelog](/docs/api/changelog).
How PDF Blocks versions the API with SemVer, what counts as a backward-compatible change, and how to pin to the v1 major with confidence.
PDF Blocks versions the API so you can adopt improvements without fear of
surprise breakage. The rules below tell you exactly which changes are safe to
receive automatically and how any breaking change would reach you.
The major version is pinned in the URL path: every action lives under /v1/,
as in https://api.pdfblocks.com/v1/add_text_watermark. Minor and patch releases
ship in place under /v1/ — you receive them automatically and never change your
URLs to get them. Because breaking changes only ever ship under a new major (a
new path segment), staying on /v1/ means staying on a stable contract.
Within v1, we make additive changes without a new major version. Treat all of
the following as things that can appear at any time, and write clients that
tolerate them:
New optional parameters on an existing action.
New accepted values for an existing parameter — a widened or expanded enum.
Parameter aliases — a new name for an existing field, with the old name
still accepted.
Richer responses — new fields in a response body or new response headers.
New actions and new endpoints.
None of these require you to pin a minor version or change your code. To stay
compatible, ignore response fields you don’t recognize rather than failing on
them, and don’t assume a fixed, exhaustive set of enum values.
A breaking change — removing or renaming a required parameter, changing a
response in an incompatible way, or altering established behavior — would only
ever ship as a new major version under a new path, such as /v2/. Your
existing /v1/ calls keep working unchanged, and you migrate on your own
schedule. We do not make breaking changes in place under /v1/.
Pin your integration to the v1 major by keeping /v1/ in your request URLs.
That is all the pinning you need: you automatically receive backward-compatible
minor and patch improvements, while breaking changes stay out of your path until
you choose to adopt a future major.
Track what changed in each release in the Changelog.
