# Versioning and deprecation

## The version is in the path

Every REST call goes to `https://api.hyperresearch.ai/v1/…`. There is no
version header and no date pin: the path is the contract.

## What /v1 promises

`/v1` is stable. Within it, changes are additive:

- new operations;
- new optional request fields and query parameters;
- new fields in responses;
- new values in enums and new error codes.

Write clients that ignore fields they do not know and handle an enum value or
an `error.code` they have not seen before. Branch on `error.code`, never on
`error.message`.

A change that would break a client written that way (removing or renaming a
field, changing a type, tightening validation on an existing field, changing a
status code) ships only under a new path version, `/v2`, alongside `/v1`.

## How deprecation works

Before an operation is removed from `/v1`, it is deprecated for **at least six
months**. From the day it is deprecated:

- the OpenAPI document at `/v1/openapi.json` marks it `deprecated: true`, with
  the removal date and its replacement in the description;
- every response from it carries the
  [`Deprecation`](https://www.rfc-editor.org/rfc/rfc9745) header (the date it
  was deprecated, as `@<unix seconds>`), the
  [`Sunset`](https://www.rfc-editor.org/rfc/rfc8594) header (the HTTP date after
  which it stops being served), and `Link: <https://hyperresearch.ai/docs/versioning>; rel="deprecation"`;
- it is listed below.

Log or alert on a `Deprecation` header in your client and you will hear about a
removal months before it happens.

## Deprecations

None. Every `/v1` operation is current.

## Rate-limit and error headers

The headers every response can carry are described in
[Errors and retries](/docs/errors/).