# Cohesivity API Versioning and Deprecation

The public REST compatibility major is version 1. Requests may send `API-Version: 1`; omitting the header selects the current supported major. HTTP responses from `/api/*` and `/edge/*` return `API-Version: 1`; WebSocket upgrade responses are excluded. An unsupported requested major returns HTTP 400 before authentication or mutation.

The REST compatibility major and a tenant runtime profile are separate. Stable URLs do not contain a runtime profile. `GET /api/status` returns the tenant's `runtime_profile`, `runtime_version`, and upgrade availability because existing tenants remain pinned until an explicit runtime upgrade. The current OpenAPI description at https://cohesivity.ai/openapi.json documents API major 1 and current stable behavior; a tenant pinned to an older runtime should use its status and release-note upgrade plan before assuming newly documented behavior.

Each OpenAPI operation carries `x-cohesivity-runtime-scope`. `front-door` operations always use the current shared control plane. `profile-aware` operations can execute on the tenant-pinned runtime or the current front door according to the resource and runtime capability rules.

## Deprecation signals

Cohesivity publishes migration guidance through tenant release notes and the runtime upgrade plan. Every REST response links this policy with `Link: <https://cohesivity.ai/docs/versioning>; rel="describedby"`. A specific endpoint or field is deprecated only when its response carries the RFC 9745 `Deprecation` header and a `rel="deprecation"` link. When removal is scheduled, the same response also carries the RFC 8594 `Sunset` header with the planned HTTP-date. No API major 1 endpoint is currently marked deprecated by this policy.

Agents should treat `Deprecation` as a migration signal, read the linked guidance, and stop creating new dependencies on that surface. They should treat `Sunset` as the latest advertised availability date, not as a guarantee that a failed or suspended resource remains usable until then.

## Rate-limit signals

Genesis responses identify the named quota and window with `RateLimit-Policy`; when the atomic limiter also has reliable current state they include `RateLimit`. Authoritative minute-quota 429 responses emit both fields. They follow draft-ietf-httpapi-ratelimit-headers-11 using RFC 9651 Structured Fields syntax. `RateLimit` reports available quota and may include `t`, the effective window in seconds within which the client can use no more than that quota; `t` does not promise when quota will be restored. A throttled response separately uses `Retry-After` for the retry delay. These fields are not emitted by every service guard.