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

# Versioning

> What can change without notice and what cannot.

The API is versioned in the path: `/v1`. For as long as `v1` exists, the contract
described in these docs holds.

## Backwards-compatible changes

These may happen **at any time and without prior notice**. Your integration must
tolerate them:

* Adding **new fields** to a response.
* Adding new **endpoints**.
* Adding **optional parameters** to a request.
* Adding **new values** to an enum (a wristband status, for instance).
* Rewording an error `message`.
* Changing the **order** of keys in a JSON object.

<Warning>
  In practice this means two concrete things: **do not validate responses with
  strict schemas** that reject unknown fields, and **do not assume enums are
  closed**. If your code does `switch (status)` with no default branch, a new
  status will break it.
</Warning>

## Breaking changes

These never happen within `v1`. They require a new version:

* Removing or renaming a response field.
* Removing an endpoint.
* Making an optional parameter required.
* Changing a field's type.
* Changing an error's `code`, or the HTTP status it is returned with.

## If a `v2` arrives

* `v1` will keep working for **at least 12 months** from the announcement.
* Notice goes by email to your integration's contact address.
* Both versions will coexist: you can migrate endpoint by endpoint.

## Checking what you are integrating against

The OpenAPI document lives on the installation itself and always matches the
deployed code:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.ventry.es/v1/openapi.json | jq '.info.version'
  ```

  ```js Node.js theme={null}
  const spec = await (
    await fetch("https://api.ventry.es/v1/openapi.json")
  ).json();

  console.log(spec.info.version);
  ```

  ```python Python theme={null}
  spec = requests.get("https://api.ventry.es/v1/openapi.json", timeout=10).json()

  print(spec["info"]["version"])
  ```

  ```php PHP theme={null}
  $spec = json_decode(
      file_get_contents("https://api.ventry.es/v1/openapi.json"),
      true
  );

  echo $spec["info"]["version"];
  ```
</CodeGroup>

No authentication is needed to read it.

There is also a browsable reference at `https://api.ventry.es/v1/docs`.

<Note>
  That live document is generated from the code in Spanish. The English reference
  in these docs is a translation of the same specification, regenerated alongside
  it.
</Note>