Versioning and deprecation

Embed
Preview of the card
<a href="https://forumulate.com/reference/versioning"><img src="https://forumulate.com/reference/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/8042f004-e3d9-445f-b7a4-b6c1f86836e6/pages/4fef5366-3124-448d-aa6c-1668063065e5/social-card.svg?v=3e7ae33eec8b" alt="Versioning and deprecation" width="600" height="315"></a>

What you can rely on, and what happens when it changes.

Send the header

Send Forumulate-Version: 2026-12-01 on every request. It is optional only so that integrations written before versioning keep working; without it you get the legacy shapes.

Forumulate-Version: 2026-12-01

The policy

  • Additive changes ship any time. A new field, a new endpoint, a new optional parameter. Write your client so an unknown field in a response is ignored rather than fatal.

  • A breaking change waits for a dated version. You ask for it by header. Older versions keep their behaviour.

  • The previous shape is served for twelve months after a new version is cut, and carries Deprecation: @<unix-seconds> and a Sunset date on the operations it affects.

Versions

Each version includes everything before it, and a version never changes once it is served: a new breaking change always gets a new date.

Version

What it changes

2026-09-01

The collection envelope: every list answers { <rows>, data, page } with a cursor. data is the same rows as the named key. See Pagination.

2026-11-01

page carries only hasMore/nextCursor (no snake_case has_more/next_cursor). Live since 2026-10-07; the official SDKs send it.

2026-12-01

An unrecognised request-body field is a 422 naming its path on every write, instead of a 200 and X-Unrecognized-Fields; a page whose slug is taken is a 409 unless you send onSlugTaken: "suffix"; a new public space joins a site only when you send siteId.

Every response says which shape it is

Forumulate-Version: 2026-12-01

A caller who states nothing is served the unversioned shape and is told so. On the operations whose shape that changes, the response also carries the deprecation:

Forumulate-Version: legacy
Deprecation: @<unix-seconds>
Sunset: Wed, 01 Sep 2027 00:00:00 GMT
Link: <https://forumulate.com/reference/versioning>; rel="deprecation"

A malformed version (v2, latest) is a 400. A date-shaped version we did not cut resolves to the shape in effect on that day.

A dated header rather than a path version, because it lets one endpoint change shape without renumbering the whole surface. Every change is announced in the changelog.

The Forumulate teamUpdated