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. Or it's explicit—you specified a version in your request. You can see how in the Using Versions doc.
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, 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 page.
Some example non-breaking changes are:
- Adding an option to a query param is non-breaking. e.g., if the param
fooprevious acceptedbarorbaz,giraffemay be added without being considered a breaking change - Making a previously required query parameter optional
- Adding optional properties to a request body
- Adding new properties to a response body.
Some example breaking changes are:
- Renaming or deleting a query parameter
- Adding a required query parameter
- Adding required properties to a request body
- Removing properties from a response body
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 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.
See How to Upgrade.
- Using Versions — How to specify a version on a request via the API key or header.
- Breaking Changes — The list of breaking changes per API version.