# Wave API Versioning and Deprecation Policy

> How the Wave Developer API is versioned, what Wave may change inside a version, and the standard headers a retiring endpoint carries so a client can act on the change without reading a changelog.

## 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.

- Strategy: url-path — the version is a path segment, so it is visible in every request and log line.
- Current version: `v1`
- Base URL: https://api.wave.co/v1
- Specification: [https://wave.co/openapi.json](https://wave.co/openapi.json)

## 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 a deprecation without polling a changelog.

### Deprecation (RFC 9745)

Structured-field date at which the endpoint became (or becomes) deprecated.

```http
Deprecation: @1735689599
```

### Sunset (RFC 8594)

HTTP-date after which the endpoint may stop responding.

```http
Sunset: Wed, 31 Dec 2025 23:59:59 GMT
```

### Link (RFC 9745)

Points at the note explaining the change and its migration.

```http
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.

## How to detect a deprecation from your client

```bash
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. Check it in CI and you will hear about a retirement from the API itself.

## Questions

Deprecation and migration questions: [support@wave.co](mailto:support@wave.co). Full developer index: [https://wave.co/developers](https://wave.co/developers).

---

## Machine-readable resources

- [Site overview for LLMs](https://wave.co/llms.txt) — product, pricing, positioning, and competitive context in one file
- [OpenAPI specification](https://wave.co/openapi.json) — every Wave API endpoint, typed
- [MCP manifest](https://wave.co/.well-known/mcp) — how to connect an agent to Wave
- [API catalog](https://wave.co/.well-known/api-catalog) — every Wave API, with spec and docs links (RFC 9727)
- [Documentation MCP server](https://wave.co/mcp) — this documentation over MCP, no authentication
- [Sitemap](https://wave.co/sitemap.xml) — every indexable URL
- [Developer portal](https://wave.co/developers) · [Contact](https://wave.co/contact)