# Versioning

The version is part of the URL: /v1. Within a version, responses change only in backward-compatible ways. Breaking changes ship in a new version at a separate URL.

## Version numbers

- **The API version** is in the path: `https://api.melioralab.io/v1`. `GET /v1/me` also returns it in the `api_version` field.
- **The event format version** is in the `api_version` field of every event. It is currently `2026-10-18`. It changes when the set of event fields changes. The value matches the format version of the same events in the organization's webhooks.

## Backward-compatible changes

These changes can appear in v1 without a new version:

- new routes;
- new optional request parameters;
- new fields in responses and nested objects;
- new event types in the feed;
- new error codes under existing HTTP statuses;
- changes to the `detail` text of errors.

## Breaking changes

We don't make these changes in v1: removing or renaming fields, changing a field's type, requiring a new parameter, or changing the meaning of existing values. If one of these becomes necessary, we'll release a new version at a separate URL. We'll announce it and the migration timeline in advance in the [changelog](https://docs.melioralab.io/en/changelog/).

## Building a resilient client

- **Ignore unknown fields** in responses. Don't fail on them.
- **Treat an unknown enum value** as `unknown`. We try not to extend v1 enums, but this code costs you nothing.
- **Skip events of unknown types**, but still save the cursor of the page they came on.
- **Handle an unknown error code** by its HTTP status.
- **Don't parse the format of IDs** or cursors: the message `id` and `next_cursor` are opaque.

## Changelog

Every API change is recorded in the [changelog](https://docs.melioralab.io/en/changelog/). The [openapi.json](https://docs.melioralab.io/en/openapi.json) specification is updated along with it.