Resources
Changelog and versioning
Every API change by date, and the 90-day notice policy for breaking ones.
Versioning policy#
The API version is in the path: /api/v1. The OpenAPI document's info.version is the date of the latest change below.
- Not breaking, shipped without notice: new endpoints, new optional request fields or parameters, new response fields, new error codes, new values in fields documented as open-ended, and changes to error
messagetext. Write clients that ignore fields they don't know. - Breaking: removing or renaming an endpoint, field, parameter or error code; making an optional input required; changing a field's type or meaning; tightening a documented limit; changing authentication.
Security fixes may ship sooner, with notice as soon as possible. The policy applies to changes after 2026-11-22; the breaking changes listed on that date shipped before any customer had integrated.
Changelog#
2026-11-22#
- changedAn error's
docslink now points at that code's entry in the catalogue (/docs/api/errors#error-<code>) instead of /docs#errors. The docs moved from one page to one page per topic; every old /docs#… link still lands on the right section. - changedFolio is now Tug. New server API keys start with
tug_(folio_keys keep working). The PostHog webhook header is X-Tug-Webhook-Secret (X-Folio-Webhook-Secret is still accepted) and the identity result header is X-Tug-Identity. The SDK istug-sdk, with the folio-sdk names kept as deprecated aliases; /folio.js and window.folio keep working for existing installs. - addedOpenAPI 3.1 description of every /api/v1 endpoint at /openapi.json, generated from the same code the API runs, and an API reference on /docs rendered from it.
- addedData subject requests with a server API key: DELETE /users/{distinctId} erases an end user and suppresses their ID, GET /users/{distinctId}/export returns everything stored about them, DELETE /suppressions/{distinctId} lifts a suppression.
- addedPOST /events, the PostHog webhook and POST /identify report data dropped for suppressed end users (
suppressed). GET /decisions returns null for them and POST /feedback answers recorded: false. - changedBreaking: Errors use one shape on every endpoint: { error: { code, message, docs, requestId } }. Branch on
code; the catalogue is on /docs/api/errors. Unknown paths and unsupported methods answer in JSON too. - addedRequest-Id on every response, and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response once the project is known.
- addedIdentity verification: userHash (HMAC-SHA256 of the user id with the project's identity secret) on GET /decisions and POST /feedback, required once a project turns it on.
- changedA decision counts as served (toward billing and frequency caps) when you report shown, not when it is fetched, so GET /decisions is safe to repeat. Server API key calls can send shown=true to count it on fetch. Responses list control-group entries in holdoutLogIds.
- removedBreaking: decision.reasoning is no longer returned by GET /decisions (it could reveal cohort membership). The dashboard still shows it.
- addedPer-user rate limits on GET /decisions and POST /feedback, alongside the per-project ones.
- fixedGoal conversions are credited only to serves before the target event's occurredAt (within 30 days), so backfilled history no longer counts.
- fixedPostHog webhook: the recommended destination body sends PostHog's event uuid, so retried deliveries are stored once. Field limits match POST /events, and $current_url fills url in every payload shape.
The SDK's own changelog is in its README on npm.