API

Versioning

One rule: your integration should never break without you choosing to move it.

Where the version lives

The version is the first segment of the path — /v1 today. A new version means a new segment (/v2), not a header or a query parameter to opt into. The current version is always the one documented here; there is no separate “latest” alias to point at, since that would silently change under you.

What ships without a new version

Most changes are additive and land inside /v1 directly, the moment they're ready — no migration, no notice needed, because nothing that already works can stop working because of them.

Change	Why it's safe
A new endpoint	Nothing existing calls it, so nothing existing is affected.
A new optional request field	Omitting it behaves exactly as it always did.
A new response field	Treat unknown fields as ignorable — every official SDK does.
A new enum value	Handle an enum you don't recognize as "something new", not as an error.
A new webhook event type	You only receive events you've subscribed to.
Loosening a validation rule	Something that failed before now succeeds — a strictly wider contract.

Build for this on day one

Deserialize response objects by field name, not by position or exact key count. Treat an enum value you don't recognize as “unhandled case,” not as malformed data. Both cost nothing to do up front and mean most of what we ship never touches your integration at all.

What forces a new version

Anything that could change the result of a call that already works gets a new version instead — never shipped into /v1 underneath you.

Change	Why it breaks something
Removing or renaming a field	Code reading it by name breaks outright.
Changing a field's type or meaning	The same name now means something different — silent, not a crash.
Removing an endpoint or a parameter	A call that worked now fails.
Tightening a validation rule	Something that succeeded before now fails.
Changing default behavior	The same request now produces a different result for existing callers.
Changing what authentication a call requires	A previously valid key stops working for that call.

How long a version keeps working

When a new version ships, the previous one keeps running unchanged for at least 12 months afterward — long enough to plan a migration around a normal release schedule, not an emergency around ours. During that window:

Every response from the deprecated version carries a Deprecation header from the day the new version ships, and a Sunset header naming the exact date it stops answering, from the day that date is set.
The change is announced in the changelog and by email to every workspace with an active API key, again 30 days before the sunset date.
A deprecated version receives security fixes for its full remaining lifetime. It does not receive new features — those are exactly what the new version is for.

After the sunset date, the old version's endpoints answer 410 Gone rather than being silently removed, so a client still pointed at it fails loudly and immediately instead of getting wrong answers.

Today

/v1 is the only version, and nothing about it is deprecated or scheduled for sunset. This page describes the commitment a /v2 would have to honor, not something in progress.