Skip to main content

API versions

The Backstage API uses dated versions - each version is named after the day it was released, for example 2026-06-13. The current version is 2026-06-13.

Within a version the API only ever changes additively: new endpoints, new optional parameters and new response fields may appear, but existing behaviour never changes. Breaking changes are only ever introduced in a new dated version, so an integration pinned to a version keeps working unchanged.

How versioning works​

  • Pin with the TL-Version header. Send the version date on every request to pin the API behaviour your integration expects. Responses echo the version that served the request in a TL-Version response header.
  • Organisations are pinned at signup. When an organisation is created it is pinned to the then-current version. Requests that omit TL-Version use the organisation's pinned version, so existing integrations are never broken by a new release.
  • SDK majors pin a version. Each major release of an official SDK hardcodes the version it speaks (the current TypeScript SDK sends 2026-06-13). Upgrading the SDK is how most integrations move between API versions.
  • Additive changes only within a version. We may add endpoints, optional request fields and response fields at any time without releasing a new version. Your integration should ignore response fields it does not recognise.
  • Twelve-month deprecation windows. When a version is deprecated you have at least 12 months before it is sunset. While deprecated, responses include Deprecation and Sunset headers telling you when the version stops being served.

Pinning a version​

curl https://api.ticketlayer.com/v1/events \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "TL-Version: 2026-06-13"

Discovering versions at runtime​

The full version list, including deprecation and sunset dates, is available from the API itself:

curl https://api.ticketlayer.com/v1/meta/versions

Version status​

VersionStatusSummaryDeprecatedSunset
2026-06-13CurrentBaseline dated version - all prior behaviour, no transforms.--

Version history​

2026-06-13​

Current

Baseline dated version - all prior behaviour, no transforms.

No breaking changes - this is the baseline dated version.

See also​