# API Versioning Overview

The Peach API uses versioning to present a consistent interface to API clients while also allowing Peach the flexibility to change the API interface as new features are developed.

All requests to Peach have a version associated with them. A version is identified by a string like `2025-03-26`. They are dates that roughly correspond to the date of that version's release.

The version used in a request is either implicit—if you don't specify one we use [the latest or the one on your API key](/developer-tools/api-keys). Or it's explicit—you specified a version in your request. You can see how in the [Using Versions](/developer-tools/using-versions) doc.

## What changes are "in" a version?

Not all changes to the Peach API go "into" a version. Only "breaking changes" go into API versions.

A non-breaking change—sometimes just called a change or a "normal" change—is when Peach adds or modifies an endpoint in a way that won't break existing clients.

For instance, Peach might add a new optional query parameter to an endpoint. Since all existing clients can simply keep using the endpoint as normal without change, it won't break existing clients, and therefore is considered a non-breaking change. As such, it is released immediately to all users regardless of API version.

### Breaking Changes

Breaking changes, on the other hand, are changes that *would* break existing clients.

For instance, if Peach added a new *required* request body parameter to an endpoint, then all clients using that endpoint would start erroring—until they changed their request to include that new parameter. i.e., this would be breaking change.

As such, breaking changes are only released in a new API version. In order to make use of the new change, you must specify the version (or newer) with which it's associated.

To see a list of available API Versions and the breaking changes associated with them visit the [API Versions Changes](/developer-tools/breaking-changes) page.

### What are example non-breaking changes?

Some example non-breaking changes are:

1. Adding an option to a query param is non-breaking. e.g., if the param `foo` previous accepted `bar` or `baz`, `giraffe` may be added without being considered a breaking change
2. Making a previously required query parameter optional
3. Adding optional properties to a request body
4. Adding new properties to a response body.


### What are example breaking changes?

Some example breaking changes are:

1. Renaming or deleting a query parameter
2. Adding a required query parameter
3. Adding required properties to a request body
4. Removing properties from a response body


## What is a beta API version?

An API version labeled as "beta" is not feature complete and is subject to change at any time. New breaking changes might be added to a beta API Version without notice.

There should only ever be one beta version; it should be the most recent API Version. Beta versions will be clearly marked as beta in the [API Versions Changes doc](/developer-tools/breaking-changes) as well as in the API Docs when a beta version is selected.

Beta API versions should not be used except in experimental environments.

If you want to build a feature using API features in a beta version, contact peach support.

## How to upgrade?

See [How to Upgrade](/developer-tools/how-to-upgrade).

## See also

- **[Using Versions](/developer-tools/using-versions)** — How to specify a version on a request via the API key or header.
- **[Breaking Changes](/developer-tools/breaking-changes)** — The list of breaking changes per API version.