Versioning

Every request must say which version of the API it was written for, in the Fansquare-Version header.

Fansquare-Version: Amethyste

The header accepts the name of a version (without accents, any case) or its release date. Amethyste and 2026-07-06 are the same version.

A missing or unknown version

A request without the header returns 400 missing_version. The error carries the current version and a header ready to copy:

{
  "type": "https://developers.offmy.co/errors/missing_version",
  "title": "Missing Fansquare-Version header",
  "status": 400,
  "detail": "Every request must pin an API version via the Fansquare-Version header.",
  "instance": "/v1/me",
  "current_version": "Amethyste",
  "current_version_date": "2026-07-06",
  "documentation_url": "https://fansquare.so/api/versioning",
  "example": "-H 'Fansquare-Version: Amethyste'"
}

A value that is not a released version returns 400 unknown_version, with the list of versions in supported_versions.

What changes without a new version

Within a version, the contract does not move: no field, parameter or endpoint you use is removed, renamed or changes type. Additive changes ship to every version at once, without a new name:

• a new field in a response;

• a new optional query parameter;

• a new endpoint;

• a new webhook event type.

Write your client so that it ignores fields it does not know. The changelog lists every additive change.

What makes a new version

A breaking change (a field removed or renamed, a type changed, a parameter made required) is released as a new version, named after the next mineral in alphabetical order. Integrations pinned to an earlier version keep receiving the shape they were written for. A version stays supported for at least 18 months after the next one is released.

Webhooks

A webhook endpoint is pinned to a version at its creation: the Fansquare-Version of the request that creates it with the API, or the current version when it is created in the app. Its payloads are rendered in that version, and api_version in each delivery gives its release date. See Webhooks.