# Versioning

The major version is in the path: `/v1`. Inside `/v1`, breaking changes ship as **dated versions**, such as `2026-11-01`.

## Choose a version

Send it in the `Vabu-Version` header.

```http
GET /v1/events
Vabu-Version: 2026-11-01
```

If you leave it out, Vabu OS uses your tenant's default. That default is pinned when you create your first key, so a new release never changes your integration by surprise. You can upgrade it in the console. Responses include `Vabu-Version` so you can see which version answered.

Webhook endpoints have their own version, so you can upgrade requests and webhooks separately.

## What is not a breaking change

These ship at any time, so write your client to tolerate them:

- New fields in responses
- New endpoints
- New event types
- New values for enums that are documented as open
- New error codes

Ignore fields you do not know. Do not fail on an unknown enum value.

## Breaking changes

A breaking change gets a new dated version, a changelog entry, and a transform layer so older versions keep working. Each older version is supported for at least 12 months.

## Spec

The OpenAPI file at `/openapi/v1.json` is the source of truth for `/v1`. The [API reference](https://docs.vabu.live/api.md) is rendered from it.