{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Versioning Overview","siteUrl":"https://docs.peachfinance.com","description":"API and product documentation for Peach Finance, a lending-as-a-service platform.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-versioning-overview","__idx":0},"children":["API Versioning Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All requests to Peach have a version associated with them. A version is identified by a string like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-03-26"]},". They are dates that roughly correspond to the date of that version's release."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The version used in a request is either implicit—if you don't specify one we use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/api-keys"},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/using-versions"},"children":["Using Versions"]}," doc."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-changes-are-in-a-version","__idx":1},"children":["What changes are \"in\" a version?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Not all changes to the Peach API go \"into\" a version. Only \"breaking changes\" go into API versions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"breaking-changes","__idx":2},"children":["Breaking Changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Breaking changes, on the other hand, are changes that ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["would"]}," break existing clients."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For instance, if Peach added a new ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To see a list of available API Versions and the breaking changes associated with them visit the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/breaking-changes"},"children":["API Versions Changes"]}," page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-are-example-non-breaking-changes","__idx":3},"children":["What are example non-breaking changes?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some example non-breaking changes are:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding an option to a query param is non-breaking. e.g., if the param ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["foo"]}," previous accepted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bar"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baz"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["giraffe"]}," may be added without being considered a breaking change"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Making a previously required query parameter optional"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding optional properties to a request body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new properties to a response body."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-are-example-breaking-changes","__idx":4},"children":["What are example breaking changes?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some example breaking changes are:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Renaming or deleting a query parameter"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding a required query parameter"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding required properties to a request body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Removing properties from a response body"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-a-beta-api-version","__idx":5},"children":["What is a beta API version?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/breaking-changes"},"children":["API Versions Changes doc"]}," as well as in the API Docs when a beta version is selected."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Beta API versions should not be used except in experimental environments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you want to build a feature using API features in a beta version, contact peach support."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-to-upgrade","__idx":6},"children":["How to upgrade?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/how-to-upgrade"},"children":["How to Upgrade"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":7},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/using-versions"},"children":["Using Versions"]}]}," — How to specify a version on a request via the API key or header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/breaking-changes"},"children":["Breaking Changes"]}]}," — The list of breaking changes per API version."]}]}]},"headings":[{"value":"API Versioning Overview","id":"api-versioning-overview","depth":1},{"value":"What changes are \"in\" a version?","id":"what-changes-are-in-a-version","depth":2},{"value":"Breaking Changes","id":"breaking-changes","depth":3},{"value":"What are example non-breaking changes?","id":"what-are-example-non-breaking-changes","depth":3},{"value":"What are example breaking changes?","id":"what-are-example-breaking-changes","depth":3},{"value":"What is a beta API version?","id":"what-is-a-beta-api-version","depth":2},{"value":"How to upgrade?","id":"how-to-upgrade","depth":2},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"API Versioning Overview"}},"lastModified":"2026-05-01T14:33:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-tools/api-versioning","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}