> ## 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 REST API is versioned in the URL path. The current major version is `v1`. The endpoints for sessions, fingerprints, agents, organizations, and webhooks live under `/v1/`.

```bash theme={"dark"}
https://api.usefoil.com/v1/sessions/sid_...
```

The [Collect API](https://usefoil.com/docs/api-reference/transport.md) that the browser and mobile SDKs call to open sessions and stream observations lives under `/v2/collect/`. The SDKs manage that transport for you, so this page describes versioning for the REST API.

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.*`, `request.*`, `rate_limit.*`) when you want broad handling; branch on the specific code only where your UX needs the precision.
* **New webhook events.** New event types may be added and delivered alongside existing ones. Acknowledge and ignore event types you don't recognize rather than rejecting them.

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.** For material changes, Foil emails the organization owner on record for each affected organization.
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 to a removed endpoint return `404` with the code `request.not_found`, and the message names the replacement where one exists. For fields, the field is simply absent from responses. A retired version of the Collect API transport returns `426` with the code `transport.upgrade_required`, and the fix is to update the browser or mobile SDK.

During the grace period, deprecated fields are clearly marked in the [API Reference](https://usefoil.com/docs/api-reference/introduction.md) 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 new major version of the REST API ships.

## When a new major version ships

If we release a new major version of the REST API, three things will be true:

* **The announcement will be early.** Foil emails organization owners on `v1` 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 call in the new version 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](https://usefoil.com/docs/quickstart.md#1-install-the-server-sdk) 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 release notes.
* **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 in a new major version, the SDK will bump to a matching major.

Pin SDK versions in your dependency manifest the way you pin any other library. Review the release notes before upgrading across major boundaries.

## Watching for changes

* [OpenAPI spec](https://usefoil.com/docs/api-reference/openapi.json) - the shape-of-truth for endpoints, fields, and enums. Diff it across releases if you need to automate detection of new fields or codes.
* SDK release notes - each server SDK publishes its release notes as GitHub Releases in its repository.
* Email - Foil emails the organization owner on record about material deprecations that affect the organization.

## What's next

> [card] [Errors](https://usefoil.com/docs/api-reference/errors.md)
>
> Branch on category prefixes, not specific codes.

> [card] [Pagination](https://usefoil.com/docs/api-reference/pagination.md)
>
> Cursor opacity and why not to parse.

> [card] [Authentication](https://usefoil.com/docs/api-reference/authentication.md)
>
> Key lifecycle across live and test environments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.