> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publishbuddy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> How API versions are exposed and what counts as a breaking vs non-breaking change.

The API is versioned in the URL. The current stable version is **`v1`**:

```http theme={null}
https://api.publishbuddy.com/v1/<endpoint>
```

When a new major version is released, it will be exposed at a new URL prefix (e.g. `v2`). The old version continues to work in parallel for a deprecation window of **at least 12 months** so you have time to migrate.

## What counts as breaking

A change is **breaking** (and therefore requires a new major version) if it:

* Removes an endpoint
* Removes or renames a request/response field
* Changes the type of an existing field
* Changes the semantics of an existing parameter (e.g. inverting a boolean's meaning)
* Tightens validation in a way that previously-valid requests now fail
* Changes the URL structure of an existing endpoint

## What counts as non-breaking

These changes can happen on the **current major version** without warning:

* Adding a new endpoint
* Adding a new optional field to a request
* Adding a new field to a response (always treat unknown response fields as ignorable in your code)
* Adding a new value to an enum (treat unknown enum values as a fallback case in your code, not a hard error)
* Performance and bug fixes that don't change documented behaviour

<Tip>
  When parsing responses, **always tolerate unknown fields**. JSON libraries do this by default in most languages — just don't enable strict schema validation against an outdated copy of the spec, or you'll break the next time we ship a non-breaking addition.
</Tip>

## Deprecation process

When something on the current version is going to be removed in the next major version:

1. We publish a **deprecation notice** in the [changelog](https://app.publishbuddy.com/changelog) and email account owners.
2. The endpoint continues to work for **at least 6 months** after the notice.
3. During that window, responses include a `Deprecation` header pointing at the replacement.
4. The next major version omits the deprecated surface entirely.

## Checking the version

Every response includes:

```http theme={null}
X-API-Version: v1
```

If you want to assert at request time that you're hitting the version you expect, check this header in your client.