> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning and deprecation

> How EvalGate versions its API contract and signals migrations to machines.

The [OpenAPI document](https://www.evalgate.com/openapi.json) is the authority
for EvalGate's public API surface. Its `info.version` identifies the current
contract. Operations and fields that are not in OpenAPI are not part of the
public contract.

## Version selection

Documented `/api/*` operations are the canonical paths. `/api/v1/*` is accepted
as a compatibility alias, but the prefix does not expose undocumented routes.
SDKs send these diagnostic headers on every request:

| Header                    | Meaning                                     |
| ------------------------- | ------------------------------------------- |
| `X-EvalGate-SDK-Version`  | Installed SDK package version               |
| `X-EvalGate-Spec-Version` | OpenAPI contract version used by the client |

Additive fields and operations can appear within the current surface. A
breaking change requires a documented migration path and a new compatible
surface or version.

## Machine-readable deprecation signals

No published operation is currently scheduled for removal. When an operation
is deprecated, EvalGate will:

* mark it `deprecated: true` in OpenAPI;
* publish its replacement and exact dates in the API changelog;
* return an [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)
  `Deprecation` header;
* return a `Link` header with `rel="deprecation"` to the migration guide; and
* return an [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) `Sunset` header
  only after a shutdown date is scheduled.

```http theme={null}
Deprecation: @1798761600
Link: <https://www.evalgate.com/docs/api/versioning>; rel="deprecation"; type="text/html"
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
```

The dates above demonstrate the header formats; they are not an announced
sunset. EvalGate publishes operation-specific dates and does not currently
promise a universal minimum migration window.

## Client behavior

Agents should treat OpenAPI `deprecated: true` or the `Deprecation` response
header as a signal to read the linked migration guide. They should stop creating
new integrations against the deprecated operation and migrate before any
published `Sunset` date.

See also [Errors](/docs/api/errors), [Authentication](/docs/api/agent-authentication), and
[Rate limits](/docs/platform/rate-limits).