# Versioning

The public API is versioned in the URL path:

```text
/api/public/v1/...
```

## What can change within v1

Within `v1`, changes are **additive only**. Build your client to tolerate:

- new endpoints and resources — v1 is read-only today, and write endpoints
  would arrive as additions;
- new **optional** fields in responses;
- new optional query parameters;
- new codes in the error catalogue;
- new scopes;
- new webhook event types.

Never assume a response object's set of fields is closed: read the fields you
know and ignore the rest. Handle an error code you do not know by its HTTP
status.

## What never changes within v1

- Existing fields and endpoints are never removed or renamed.
- The type and meaning of an existing field never change.
- An existing error code keeps its meaning.
- Authentication (`X-Api-Key`), the error envelope and the pagination shapes
  stay as documented.

## Breaking changes → a new version

Anything that would break the rules above ships under a new path version,
`/api/public/v2/...`, announced in the [changelog](/changelog) together with
migration notes and how long `v1` stays available.

## Webhooks

Webhook payloads carry no version. Read them the same way: take the fields you
know, ignore the rest, and treat an event type you do not know as one to skip.

## Staying informed

Watch the [changelog](/changelog): every addition to the API is recorded
there, release by release.
