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

# Versioning and deprecation

> How the API changes, how you learn which version you are talking to, and how much notice a removal gets.

## One major version, dated revisions

The API has one major version, in the path: `/api/v1`. Within it, the contract (paths, parameters, response
fields and their types) changes by **dated revisions**. The revision is the UTC date the contract last changed,
for example `2026-11-01`.

* The [OpenAPI spec](https://astreus.ai/openapi.json) carries it as `info.version`.
* Every response from `/api/v1` carries it in the `x-astreus-api-version` header.

A date was chosen over semantic version numbers because `/api/v1` only ever takes additive changes (see
below), so a minor/patch number would carry no information a client can act on, while a date says when the
contract moved and lines up with the deprecation windows, which are also dates. The revision moves only when
something a client can depend on changes: a path, a method, a parameter (name, type, allowed values, maximum,
required), a request body or a response schema. Rewording a description or refreshing an example keeps it.

To detect a change, compare the header (or `info.version`) with the value your client was built against. The
spec at `https://astreus.ai/openapi.json` is always the one the live API serves, and the API Reference tab on
this site is built from it.

## What is a breaking change

A breaking change is one that can make a correct client fail or read a wrong value:

* removing or renaming a path, a parameter or a response field;
* changing a field's type, unit, sign convention or meaning (a fraction becoming a percent, a string becoming an
  array);
* making an optional parameter required, narrowing its allowed values or lowering its maximum;
* changing a default in a way that changes which rows come back (order, window, page size);
* turning a `200` into an error for a request that used to succeed.

These never happen inside `/api/v1` without the notice below. A change that cannot keep the old behaviour
alongside goes to a new major version (`/api/v2`), and `/api/v1` keeps serving.

Not breaking, and made without notice:

* adding a path, an optional parameter, a response field, an enum value in a response, or an error `code`;
* raising a maximum;
* fixing a value that was wrong (a missing value served as `0` becomes `null`, a mislabelled period is
  corrected): a wrong number is a bug, not a contract;
* refusing a request that was always invalid (an unknown parameter, a value outside the documented range) with
  a `400` instead of silently ignoring it.

Write clients that ignore fields they don't know and treat an unknown `code` by its HTTP status.

## Deprecation

When a field, parameter or path is going away:

1. It is marked `deprecated: true` in the spec, and its description names the replacement and the earliest
   removal date. Where a replacement exists, both are served side by side (for example a snake\_case pointer
   `next_offset` beside `nextOffset`).
2. It keeps working for **at least 90 days** from the revision that deprecated it.
3. Removal ships in a later dated revision, listed with the other contract changes.

Watch for `deprecated: true` in the spec when you regenerate a client.

## Releases

The API is released as part of the Astreus web application. The spec is generated from the route table at build
time, so the live `/openapi.json`, the `x-astreus-api-version` header and the API reference describe the same
build. The reference on this site is rebuilt from the live spec after each release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.