# Versioning

Skribble versions its REST APIs so you can rely on stable behavior while we keep improving the platform. There are two kinds of change:

- **Breaking changes** are released in a **new API version**, and we provide advance notice before they go live.
- **Additive, non-breaking changes** are rolled out to **all supported versions** without requiring any action from you.

The sections below explain exactly what falls into each category.

## Breaking changes

Breaking changes are changes that can potentially break an integration. They are always released in a **new API version**, and we provide advance notice before doing so. Breaking changes include:

- Removing an entire operation
- Removing or renaming a parameter
- Removing or renaming a response field
- Adding a new required parameter
- Making a previously optional parameter required
- Changing the type of a parameter or response field
- Removing enum values
- Adding a new validation rule to an existing parameter
- Changing authentication or authorization requirements
- Changing the semantics or behavior of an existing operation

## Additive changes

Additive (non-breaking) changes should not break an integration and are made available in **all supported API versions**. Additive changes include:

- Adding an operation
- Adding an optional parameter
- Adding an optional request header
- **Adding a response field**
- Adding a response header
- Relaxing or widening a validation rule on an existing parameter
- **Adding enum values**, provided your integration is built to tolerate unknown values

:::info{title="New response fields and enum values can appear at any time"}

The two highlighted changes above ship to **all supported versions without advance notice**. Build tolerant clients: ignore unknown fields in responses, and accept new enum values rather than rejecting them. Integrations that fail on an unexpected field or enum value will break as we ship improvements — even though no breaking change was released.

:::

## Versioning scheme

Each API declares its version in the `info.version` field of its OpenAPI specification, following [semantic versioning](https://semver.org/) (`major.minor.patch`):

- **Major:** reserved for breaking changes, released as a new versioned API (for example, Sign API v2 to v3).
- **Minor:** additive, non-breaking changes always increase the version by a minor increment (`x.y.z` to `x.(y+1).0`).
- **Patch:** corrections and clarifications that do not change behavior.

The major version is selected by the base URL path (for example, `.../v2` versus `.../v3`). Minor and patch updates are applied automatically to whichever version you call — there is no way, and no need, to pin a specific minor or patch version.

## Version support

When a new REST API version is released, the previous version continues to be supported for an extended transition period, giving you time to migrate.

For the Sign API specifically, including the v1 end-of-support date and the v2 vs. v3 feature comparison, see [Sign API versions](/sign-api-versions).