Skip to content
Sencai.docs

API versioning

The Platform API is versioned by URL path - every endpoint in this section lives under /api/v1. There is currently one version, v1; this page documents how the platform tracks version lifecycle information so your integration isn’t surprised if that changes.

Why this matters even with one version

Section titled “Why this matters even with one version”

The intent is that a breaking change to the API arrives as a new version rather than changing /api/v1 out from under integrations that already depend on it - /api/v1 keeps working exactly as documented for as long as it’s listed as current (or still supported) on the API Versions screen. Building against /api/v1 explicitly today, rather than assuming a default, is the cheapest thing you can do now to be ready for that.

What the API Versions screen shows

Section titled “What the API Versions screen shows”

Settings → API Versions (/gravity/settings/api-versions) lists every version record the platform maintains, each with:

  • Version - the version string, such as v1.
  • Description and Current - whether this is the recommended version (a green Current badge).
  • Deprecated - a chip showing the date a version was or will be marked deprecated, if set.
  • Sunset - a chip showing the date calls to that version stop working, if set.
  • Breaking changes - a collapsible list of what changed.
  • A link to a migration guide, when one is provided.

Adding or editing a version record is a platform-admin action; as a customer you use this screen to check status, not to manage it.

The same records are also readable directly - GET /api-version-policies (and GET /api-version-policies/{id} for one record) returns the same version/description/deprecated_at/sunset_at/breaking_changes/ migration_guide_url fields, authenticated with your signed-in session. This isn’t part of the personal-access-token surface described in API tokens - it’s for checking status from the app’s own context rather than from an unattended script.

How deprecation is intended to work

Section titled “How deprecation is intended to work”

Once a future version is marked deprecated, calls made against it are meant to carry standard deprecation signaling:

Deprecation: 2027-01-15
Sunset: 2027-04-15
Link: <https://example.com/migration-guide>; rel="deprecation"

A Deprecation response header carries the deprecation date, Sunset carries the date it stops working, and Link points at the migration guide, per RFC 8594. After the sunset date passes, calls to that version are meant to be rejected outright with 410 Gone.

What to do when a version is deprecated

Section titled “What to do when a version is deprecated”
  1. Read the breaking_changes list and follow the migration guide link on the API Versions screen (or in the response body) to see exactly what’s changing.
  2. Move your integration to the new version’s path prefix before the sunset date.
  3. If you won’t be able to migrate before the sunset date, contact your account team well before it arrives, not after calls have already started failing.

Pinning and upgrading

Section titled “Pinning and upgrading”

Since there’s only one version today, there’s nothing to pin against or upgrade to yet. Call /api/v1 explicitly, as every example in this section already does, rather than assuming a default - that’s the safest habit to have in place before a second version ever ships.

What’s next

Section titled “What’s next”