API versioning

The Driftstack API is currently at v1. This page covers how versioning works, what we consider a breaking change, and how deprecation timelines are communicated.

How versions are expressed

Every endpoint is prefixed with /v1/. The version lives in the URL, not in a header, so callers always know which contract they're hitting. Example:

POST https://api.driftstack.dev/v1/sessions
GET  https://api.driftstack.dev/v1/profiles
POST https://api.driftstack.dev/v1/agent-sessions

Breaking changes use a new major prefix such as /v2/ in parallel with v1, so old clients keep working during the announced migration window.

Definition of a breaking change

Breaking changes increment the major version (v1 → v2). The following are breaking:

• Removing an endpoint.
• Removing a field from a response.
• Changing the type of a response field (e.g. string → number).
• Renaming a field.
• Adding a new required field to a request body.
• Changing the meaning of an existing status code.
• Tightening validation on an existing field (e.g. shrinking the max length, restricting the regex).
• Changing the URL path or HTTP method of an endpoint.

The one exception is a security fix: it can be breaking and still ship on v1, at once.

Non-breaking changes (no version bump)

• Adding a new endpoint.
• Adding a new field to a response.
• Adding a new optional field to a request body.
• Loosening validation (longer max length, broader regex).
• Adding a new value to an enum field whose schema is documented as open-ended (e.g. status may gain new states over time — clients should default-handle unknown values).
• Adding a new event type to the webhook event stream.
• Performance improvements that don't change observable behaviour.

Build clients defensively against the "open enum" cases — handle unknown status values gracefully rather than crashing on them. The SDKs do this automatically; if you handcraft a client, do the same.

Security fixes

A breaking change that closes a credential or authorization leak — a request that could read, redirect or use a secret, or reach something the caller is not allowed to — does not wait for a new major version or the deprecation timeline below. Every day of notice would be a day the leak stays open, so it ships immediately on /v1/, without a Deprecation or sunset window; it is announced under Security in the API changelog when it ships, with what was accepted before, what is refused now, the exact error and what to send instead; and, where the affected accounts can be identified, those customers are contacted. It is kept as narrow as the fix allows: only the requests that could carry the leak change, and they are refused with an error that says what to send — never silently accepted with a different meaning. The same clause is in the API reference.

Deprecation timeline

When we decide to deprecate something within v1 (rare — we'd usually wait for v2), the timeline is:

1. Day 0: Deprecation announced in the API changelog and via a Deprecation response header on the affected endpoint, with a Sunset header (RFC 8594) that carries the sunset date.
2. Day 0 → 90: Endpoint continues to work unchanged. We email accounts that have called the endpoint in the last 30 days at the 60-day and 30-day marks.
3. Day 90+: Endpoint returns a non-fatal 410 Gone with a pointer to the replacement.

Major version transitions (v1 → v2) follow a longer schedule: minimum 12 months of parallel availability, with the same 60-day / 30-day email reminders.

Detecting the current version

The version is in the URL path — every endpoint is prefixed with /v1/. If you handcraft a client, log the base URL alongside your request id so you can diagnose "is my SDK pinned to the right URL?" issues. The X-Request-Id header is always set on the response; our SDKs surface it on every typed error.

Beta endpoints

No customer-facing endpoints are in beta today — the surface under /v1/ is stable per the breaking-change policy above. Any beta path is explicitly labeled on its docs page and announced in the API changelog before use.

What "v1" guarantees about behaviour

As long as you stay on v1, you get:

• The same URL paths.
• The same response shapes (additive fields only).
• The same status-code semantics.
• The same authentication scheme (Bearer API key or OAuth).
• The same idempotency semantics (DELETE is idempotent, POST creates new resources, PUT/PATCH are explicit replacements).

The one exception is a security fix, which can refuse a request v1 used to accept.

SDK version vs API version

The official SDKs (TypeScript, Python, Go) follow semver independently of the API. SDK 0.x is the current pre-1.0 line — surface is stable for the published methods but new resources land in minor versions. SDK majors and API majors are independent: a supported SDK 1.x can still target API /v1/, while an SDK targeting API /v2/ uses SDK 2.x.

Support

Versioning, deprecation, or migration questions: [email protected]. Deprecation announcements are in the API changelog.