Skip to main content
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.
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.

​
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:
No authentication is needed to read it. There is also a browsable reference at https://api.ventry.es/v1/docs.
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.