Versioning and deprecation

The current version is 2026-10-30. What changed in each version is in the changelog.

Choosing a version

• Send Collects-Version: 2026-10-30 on every request. Every response names the version that served it in the same header.
• A request without the header is served the oldest version still served, today 2026-10-30, so a client that never sends it keeps the meanings it was built against until that version is retired.
• A version this API does not serve is refused with 400 invalid_request, and the message names the versions it does serve. Nothing else runs.

What needs a new version

• Additive changes need none. A new operation, a new optional input, a new response field, a new event type or a new error code can appear in every version at any time. Ignore fields you do not know.
• A change of meaning ships only as a new dated version: a field that comes to mean something else, a status that applies at a different time, or a stricter rule on an existing input. Your requests keep the old meaning until you change the header.

Webhooks

A webhook subscription is pinned to the version of the request that created it, shown as api_version on the subscription. Every delivery carries Collects-Version with that version, so an event keeps its meaning for that endpoint whatever version your later calls use. To move an endpoint to a newer version, create a new subscription with the newer header and delete the old one. The Zapier and Make apps send the header for you.

Removals

An operation, field or event type is removed only after it has been announced in the changelog and marked on every response of that operation with the Deprecation header (RFC 9745, the date it was announced) and the Sunset header (RFC 8594, the date it stops), at least 180 days before it happens. A version stays served for at least 12 months after the next one ships.

Claude and other MCP clients

MCP tools are never renamed or removed in place. A tool whose meaning changes ships under a new name, and the old one says it is deprecated, in its description and in the changelog, for the same 180 days. Your MCP client reads the tool list again on each connection, so it needs no header.

Before go-live

Before the API had customers, fields that disagreed with what the Collects app shows were corrected in place. The changelog lists each one under 2026-10-30.