# Versioning and compatibility

> What changes the API makes without notice, and what it promises not to change.

Page: https://docs.aggre.org/reference/versioning · Section: Reference · All pages: https://docs.aggre.org/llms.txt

## The promise {#promise}

The data API is `/v1`. Within `/v1`, changes are **additive**:

- New routes, new optional query parameters and new fields in responses can appear at any time.
- Existing routes, parameters and fields are not removed or renamed, and their meaning does not change. A series whose meaning would change gets a new id.
- New `error.code` values can be added; clients must tolerate codes they do not know.
- New values can appear in documented enums such as `meta.status`; handle unknown values gracefully.

Write clients that **ignore unknown fields** and tolerate unknown codes. The `meta` object in particular grows keys per family.

## What can change without notice {#changes}

| Change | Example |
|---|---|
| A dataset starts or stops holding data | A source is switched on after its terms are read; a source is paused. Read `meta.status`. |
| Rows change content | A publisher revises a number, a statute is amended, a record is delisted. Revisions are kept as versions or marked removed; see [Freshness](https://docs.aggre.org/concepts/freshness.md). |
| Limits are adjusted | Rate limits, default key quotas and freshness windows are deployment settings. |
| Attribution text changes | `credit` is the publisher's current wording. |

## Contract files {#contract-files}

The OpenAPI files and JSON Schemas on this site are generated from the same contract the service is tested against. The data API file is checked against the service's router in the service's own tests, so a route cannot exist without being in the spec. If you find the docs and the API disagreeing, the API's behaviour is what you observed; please report it with the `x-request-id`.

## This documentation {#docs}

Pages are rebuilt from the contract when it changes. Anything on a generated page ("Generated from ...") follows the contract exactly; authored guides are written to match it. The Markdown and `llms.txt` outputs are rebuilt with them.