Skip to content

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:

http
GET /management/contracts HTTP/1.1
Host: api2.sesamy.com
Authorization: Bearer <token>
Sesamy-Version: 2026-11-18

Any 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:

json
{
  "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:

  1. The Sesamy-Version header.
  2. The version pinned to your API client, if it has one.
  3. 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:

typescript
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:

ChangeWhat your code must do
New endpointsNothing
New optional request parameters or body fieldsNothing
New fields in responsesIgnore fields you don't know. Don't fail on unknown properties
New values in enums such as statuses and event typesHandle values you don't know, for example by treating them as "other". Don't use an exhaustive switch that throws
New error code valuesFall back to the HTTP status when you don't recognise the code
New webhook event typesIgnore 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 documentedDon't depend on order
The text of message in errorsBranch on code, never on message
Fixing behaviour that contradicts the documentationFollow 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:

HeaderMeaning
DeprecationWhen it was deprecated, as @<unix seconds> (RFC 9745)
SunsetThe date after which it may be removed (RFC 8594). Only sent once a removal date is set
Linkrel="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 ​

  1. Read the breaking changes in the API Changelog dated after your current version, up to and including the version you're moving to.
  2. Update your code for each one.
  3. Test against the new version by sending it in Sesamy-Version.
  4. Release with the new header value.

Next Steps ​

Released under the MIT License.