Versioning and changelog

The /v1 path never changes. Breaking changes ship as dated versions instead, and every request runs under one. Additive changes (new endpoints, new fields in a response, new webhook topics) don't need a new version, so your client must ignore fields it doesn't know.

Choosing a version

The version a request runs under is, in order:

1. The referally-version header, when you send one:

   curl https://referalli.com/v1/referrals \
     -H "Authorization: Bearer $KEY" \
     -H "referally-version: 2026-11-01"

2. Otherwise, the version the API key is pinned to.

3. Otherwise (browser sessions without the header), 2026-10-21.

Every response echoes the version it used in a referally-version header. An unknown version returns 400 with the supported ones in the message.

Key pins

A new API key is pinned to the latest version when it's created. Pass apiVersion to pin it to another:

curl -X POST https://referalli.com/v1/api-keys \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"name": "billing sync", "apiVersion": "2026-10-21"}'

Keys created before versioning existed are pinned to 2026-10-21, so nothing changes for them. To upgrade a key, test with the header first, then move the pin:

curl -X PATCH https://referalli.com/v1/api-keys/key_01J... \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"apiVersion": "2026-11-01"}'

GET /v1/api-keys shows each key's apiVersion. Moving a pin is audited and needs the owner or admin role.

Deprecation policy

A version stays supported for at least 12 months after the next one ships. Deprecated versions are announced in this changelog, and in a referally-deprecation response header, at least 6 months before they stop being served. API keys keep their pinned version until you change it.

GET /v1/versions (no credentials needed) returns the latest version, every version with its changes, and this policy as JSON.

Changelog

2026-11-01

• Paginated lists. Every list endpoint returns { "object": "list", "data": [...], "has_more": true, "next_cursor": "..." } and pages with limit, starting_after and ending_before, with no hard cap. See Pagination.

• Lists over timestamped records accept created[gte] and created[lte].

2026-10-21

• Baseline. Lists return a plain JSON array, capped per endpoint (for example 500 referrals or commissions, 200 payouts).