# Versioning

> The version is in the URL. v1 only changes in ways that don't break a careful client.

Source: https://taseli.co.il/en/developers/versioning

Base URL: `/api/v1`. Webhook bodies carry `"apiVersion": "v1"`.

## What can change in v1

- New endpoints, new optional parameters, new response fields.
- New values in lists that aren't closed: `kind`, `source`, `decidedVia`, a new event type.
- The wording of `message`, titles and texts.

So ignore fields you don't know, treat an unknown value as "other", and branch on `code`, not `message`.

## What can't

- Removing or renaming a field, endpoint, parameter or error code.
- Changing a field's type or meaning.
- Tightening what a request accepts, except to close a security hole.

A breaking change ships as `/api/v2`. v1 keeps running for at least 6 months after that, with notice to the owner of every key in use.

## Where changes are announced

In the [changelog](https://taseli.co.il/en/changelog). The [OpenAPI document](https://taseli.co.il/api/v1/openapi.json) is always the current contract.