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 header (the date it was deprecated, as @<unix seconds>), the Sunset 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.