Skip to main content
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/.
The Collect API 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 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 follow their own semver 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 - 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

Errors

Branch on category prefixes, not specific codes.

Pagination

Cursor opacity and why not to parse.

Authentication

Key lifecycle across live and test environments.