> ## Documentation Index > Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Versioning > Learn how Foil API versioning works under /v1/, which changes are additive versus breaking, and how deprecations, sunsets, and SDK releases ship. The Foil API is versioned in the URL path. The current major version is `v1`, and every public endpoint lives under `/v1/`. ```bash theme={"dark"} https://api.usefoil.com/v1/sessions/sid_... ``` Version numbers in the path signal major, breaking releases. Inside a major version, the API evolves continuously — we add fields, enum values, and endpoints without bumping the version. Pinning to `/v1/` gives you a stable contract for the life of that major. ## What's additive (safe to adopt) The following kinds of changes can appear inside a major version without notice, and your integration should handle them gracefully: * **New endpoints.** New paths under `/v1/` may be added at any time. * **New optional request fields.** New parameters on existing endpoints are always optional — existing requests continue to work unchanged. * **New response fields.** Additional fields may be added to any response object. Treat response shapes as open — deserialize the fields you care about and ignore the rest. * **New enum values.** New values may be added to existing enums (verdict categories, attribution facets, error codes). Don't switch on a closed set; include a default branch. * **New error codes.** The error `code` namespace grows over time. Branch on the category prefix (`auth.*`, `validation.*`, `rate.*`) when you want broad handling; branch on the specific code only where your UX needs the precision. * **New webhook events.** For Gate webhooks and any future webhook surfaces, new event types may be delivered alongside existing ones. Unknown event types should be acknowledged and ignored, not rejected. In short: unknown fields, values, and events should never crash your integration. Plan for them from day one. ## What's breaking (announced in advance) Changes that could break an existing integration get a version bump or, for surgical cases, a deprecation notice with a migration path. Examples of what counts as breaking: * Removing a field from a response * Renaming a field * Changing a field's type (`string` → `number`, nullable → non-nullable, etc.) * Changing the semantics of an existing field or enum value * Removing an endpoint * Making a previously-optional field required * Changing authentication requirements on an endpoint * Changing the default behavior of an endpoint in a way that surprises existing callers We do not ship these silently on `/v1/`. ## Deprecation and sunset When a specific endpoint, field, or behavior needs to go, we follow a staged process inside the current major: 1. **Announcement.** The deprecation is published in the [Changelog](/resources/changelog), highlighted in the dashboard for affected organizations, and (for material changes) emailed to the organization owner on record. 2. **Grace period.** The old behavior continues to work alongside the new one. The documented sunset date is never less than 90 days from the announcement for live-mode behavior; test-mode deprecations may be shorter. 3. **Sunset.** After the grace period, the old behavior is removed. Requests that still use it return a `410 Gone` (or, for fields, the field is simply absent from responses). During the grace period, deprecated fields are clearly marked in the [API Reference](/api-reference/introduction) pages and in OpenAPI schema output. ## Pinning to a version The only version pin you need is the `/v1/` in the URL. As long as you keep calling `/v1/`, you'll stay on the stable major contract. We do not offer dated API versions (e.g. `API-Version: 2025-04-16`) — additive evolution inside `/v1/` is the design. If that ever changes, the current `/v1/` contract is what we'd continue to honor until a `/v2/` release. ## When a new major version ships If we release `/v2/`, three things will be true: * **The announcement will be early.** Major versions are announced in the changelog, the dashboard, and (for customers on `v1`) by email at least 180 days before `v1` is scheduled for sunset. * **Both versions will run in parallel.** Your `/v1/` integration keeps working through the overlap. * **A migration guide will be published.** Every breaking change will be listed, with the equivalent `/v2/` call for each `/v1/` pattern. We do not plan to retire `/v1/` in the foreseeable future. This section exists so the policy is clear if and when we do. ## SDK versioning The [server SDKs](/api-reference/introduction) follow their own [semver](https://semver.org/) release cadence, independent of the API version: * **Patch releases** (`x.y.z` → `x.y.z+1`) — bug fixes and dependency updates. Safe to upgrade without reading the changelog. * **Minor releases** (`x.y.z` → `x.y+1.0`) — new endpoints, new helper methods, new SDK-level features. Backwards-compatible with existing code. * **Major releases** (`x.y.z` → `x+1.0.0`) — breaking SDK changes: renamed methods, changed return types, dropped support for old Node/Python/Go versions. Migration notes are published with each major. An SDK major can ship without an API major, and vice versa. The SDKs track API changes closely — when the API adds a new endpoint or field, the next SDK minor typically exposes it. When a breaking API change ships under `/v2/`, the SDK will bump to a matching major. Pin SDK versions in your dependency manifest the way you pin any other library. Review changelogs before upgrading across major boundaries. ## Watching for changes * [Changelog](/resources/changelog) — the authoritative list of API and SDK changes. * [OpenAPI spec](/api-reference/introduction) — the shape-of-truth for endpoints, fields, and enums. Diff it across releases if you need to automate detection of new fields or codes. * Dashboard notices — material deprecations affecting your organization show up in the dashboard's announcement area. ## What's next Branch on category prefixes, not specific codes. Cursor opacity and why not to parse. Dated list of API and SDK changes. Key lifecycle across live and test environments.