Versioning
How the Sesamy API versions its behaviour, what can change without a new version, and how you upgrade.
Overview
The Client and Management APIs are versioned by date. A version is the API's behaviour as it was on that day, for example 2026-11-18. You choose a version, and the API keeps answering you that way.
- Breaking changes are tied to a version. You only get them when you move your version to their date or later, so you decide when to upgrade.
- New features reach every version as soon as they ship. You don't need a newer version to use a new endpoint or field.
Every change, breaking or not, is listed in the API Changelog.
Choosing a version
Send the Sesamy-Version header with every request:
GET /management/contracts HTTP/1.1
Host: api2.sesamy.com
Authorization: Bearer <token>
Sesamy-Version: 2026-11-18Any date up to today, in UTC, is valid. A date selects every breaking change dated on or before it, so a date before the first version (2026-11-18) gets the same behaviour as 2026-11-18. The API refuses an empty value, a malformed date, or a date after today in UTC with 400:
{
"code": "INVALID_API_VERSION",
"message": "Sesamy-Version must be a date in the form YYYY-MM-DD, for example 2026-11-18."
}Once the API has resolved your version, the response includes it in the Sesamy-Version response header, so you can check which behaviour you got. A 400 INVALID_API_VERSION response has no version to echo, so it doesn't carry this header.
If you don't send a version
The API uses, in order:
- The
Sesamy-Versionheader. - The version pinned to your API client, if it has one.
2026-11-18, the behaviour from before versioning existed.
A request without the header never gets the latest version automatically. An integration that never sends a version keeps working the way it did when it was built.
Set the header explicitly
Send Sesamy-Version from your own code even if your client has a pinned version. Then the version you are tested against lives with your code, and upgrading it is a reviewed change.
The Sesamy SDK
@sesamy/sdk sends the version its release is built against. Its TypeScript types match that version's responses, so upgrading the SDK is how you upgrade the version. To try a newer version before upgrading the SDK, set apiVersion:
import { management } from '@sesamy/sdk';
const api = management({
baseUrl: 'https://api2.sesamy.com',
tokenProvider: async () => `Bearer ${token}`,
apiVersion: '2026-11-18',
});What we change without a new version
These changes ship to every version. Build your integration to tolerate them:
| Change | What your code must do |
|---|---|
| New endpoints | Nothing |
| New optional request parameters or body fields | Nothing |
| New fields in responses | Ignore fields you don't know. Don't fail on unknown properties |
| New values in enums such as statuses and event types | Handle values you don't know, for example by treating them as "other". Don't use an exhaustive switch that throws |
New error code values | Fall back to the HTTP status when you don't recognise the code |
| New webhook event types | Ignore event types you didn't subscribe to or don't know |
| The order of fields in a response, and of list items where no sort order is documented | Don't depend on order |
The text of message in errors | Branch on code, never on message |
| Fixing behaviour that contradicts the documentation | Follow the documentation |
When an enum is documented as complete (closed), adding a value to it is a breaking change instead.
What needs a new version
These are breaking changes. They only reach you when you move your version to their date or later:
- Removing or renaming an endpoint, parameter, or response field
- Changing a field's type or format, or making it nullable
- Making an optional parameter required, or adding a new required one
- Changing a default value or the side effects of a request
- Returning a different HTTP status for the same situation
- Adding a value to an enum documented as closed
Each breaking change in the API Changelog says what you have to change before you move your version to its date or later.
Deprecations
Before something is removed, it is deprecated. A response that uses a deprecated feature carries these headers:
| Header | Meaning |
|---|---|
Deprecation | When it was deprecated, as @<unix seconds> (RFC 9745) |
Sunset | The date after which it may be removed (RFC 8594). Only sent once a removal date is set |
Link | rel="deprecation", pointing at the changelog |
Log these headers in your integration so you find out early. We record which API clients still use each deprecated feature, and we contact you before removing anything you use.
Upgrading
- Read the breaking changes in the API Changelog dated after your current version, up to and including the version you're moving to.
- Update your code for each one.
- Test against the new version by sending it in
Sesamy-Version. - Release with the new header value.
Next Steps
- API Changelog: every change, with migration notes
- Error Handling: error codes and how to handle them
- Sesamy SDK: typed access to the API
- Handling Webhooks