# Versioning

> What v1 in the path and api_version in each event mean, and the current state of the contract.

Page: https://safeonuba.com/en/developers/versioning · SafeOnuba API v1 (`api_version: "2026-09-24"`), in preview: the contract may change.

The API has two version marks, and each says something different.

## v1 in the path

All paths are under `/v1`. It is the major version of the contract: the paths, the objects and what they mean.

## api_version in each event

Each event carries `api_version: "2026-09-24"`, and the webhooks’ `User-Agent` repeats it (`SafeOnuba-Webhooks/2026-09-24`). It is the date of the version of the format that event was generated with.

Store it alongside each event you receive. If formats ever coexist, it is what will tell you which one each was written with.

## Current state: preview

> **v1 · preview**
>
> The v1 contract is awaiting sign-off from the first customer and **may change**. Any change will be noted in the [changelog](https://safeonuba.com/en/developers/changelog), and the published contract always prevails.

While the preview lasts:

- Generate your client, if you do, from the contract ([OpenAPI 3.1](https://safeonuba.com/en/developers/openapi.json)) and regenerate it when it changes.
- Ignore fields you don’t recognise instead of failing. It is the simplest way to stop a new field breaking your integration.
- Program against the `code` of errors and against enum values, not against texts.

## The contract

The OpenAPI 3.1 contract is the source of truth: the [reference](https://safeonuba.com/en/developers/reference) in this documentation is generated from it on every deployment. You can download it at [/en/developers/openapi.json](https://safeonuba.com/en/developers/openapi.json), and the API serves it at `GET /v1/openapi.json`, without a token.