Skip to main content

​
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 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.