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 docs link 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 is tug-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.

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides