Wave API Versioning & Deprecation Policy

Versioning

Every endpoint is versioned in the URL path. A breaking change ships as a new version prefix; the previous version keeps working while it is deprecated. The current version is v1, at api.wave.co/v1, and its complete surface is described in the OpenAPI specification. The version is a path segment, so it is visible in every request, log line, and saved example.

Changes Wave may make inside a version

Write clients that tolerate these. None of them will bump the version prefix.

New endpoints, new optional request parameters, new response fields
New enum values in fields documented as extensible
Relaxed validation, or a new optional authentication scope

Changes that require a new version

These never happen inside an existing version prefix.

Removing or renaming an endpoint, field, or enum value
Making an optional parameter required, or narrowing accepted values
Changing the type or meaning of an existing response field

How a deprecation is signalled

A deprecated endpoint keeps working and starts sending these response headers. All three are standards, so a client can detect the deprecation mechanically.

Deprecation (RFC 9745): Structured-field date at which the endpoint became (or becomes) deprecated.Deprecation: @1735689599
Sunset (RFC 8594): HTTP-date after which the endpoint may stop responding.Sunset: Wed, 31 Dec 2025 23:59:59 GMT
Link (RFC 9745): Points at the note explaining the change and its migration.Link: <https://wave.co/developers>; rel="deprecation"; type="text/html"

Notice period

Wave gives at least 90 days between the Deprecation date and the Sunset date on any endpoint scheduled for removal. That is a floor, not a target — expect more. What else is committed:

v1 keeps its current behaviour. Anything in the breaking-change list above ships under a new version prefix instead of changing v1 underneath you.
A deprecated endpoint keeps responding while it carries the Deprecation and Sunset headers. It is never removed silently.
Sunset states the date after which an endpoint may stop responding, so the deadline is machine-readable from the response itself rather than announced only in a changelog.

Currently deprecated endpoints

None. No endpoint in v1 is deprecated, and no Sunset date is set on any Wave API endpoint.

Detect a deprecation from your client

curl -sSI https://api.wave.co/v1/sessions \
  -H "Authorization: Bearer $WAVE_API_TOKEN" \
  | grep -iE '^(deprecation|sunset|link):'

An empty result means the endpoint is not deprecated. Run it in CI and you will hear about a retirement from the API itself.

Questions

Deprecation and migration questions go to support@wave.co. The full developer index is on the developer portal.

API versioning and deprecation policy