API reference

API versioning and deprecation policy

How Canviq versions its public API: the /api/v1 support window, what counts as a breaking change, and how Sunset and Deprecation are communicated.

Versioning scheme

The public REST API is versioned in the URL: /api/v1/*. A future breaking change ships as /api/v2/* rather than changing the behavior of /api/v1/* in place. The MCP server uses its own protocol-level versioning and is not covered by this policy. The iOS SDK and web embed follow whichever REST API version they target.

Support window

v1 is supported for 12 months after v2 ships.
The Sunset header is set 90 days before the v1 removal date.
A deprecation notice email is sent to organization admins with active API keys 30 days before the Sunset date.
After the Sunset date, v1 endpoints respond with 410 Gone.

Response headers

Every /api/v1/* response carries API-Version: 1. Once v1 enters its sunset window, three additional headers appear:

API-Version: 1
Sunset: Thu, 01 Jan 2027 00:00:00 GMT
Deprecation: Wed, 01 Oct 2026 00:00:00 GMT
Link: <https://canviq.app/api/docs>; rel="deprecation"

Sunset (RFC 8594) is the date and time after which the endpoint is removed.
Deprecation (RFC 9745) is the date the endpoint was deprecated, which is the v2 general-availability date.
Link points to the migration guide and is present only alongside Sunset, since a sunset date is the signal that callers must act.

Breaking changes

These require a new API version.

Removing a field from a response
Changing a field's type
Removing an endpoint
Changing authentication requirements, such as a new required header or key format
Changing the error response format

Not breaking changes

These ship under the current version.

Adding a new field to a response
Adding a new endpoint
Adding a new optional query parameter
Adding a new scope
Adding a new error type, as long as existing error types are unchanged

API error reference