# Versioning

> What can change in v1 without notice, what never changes, and how a breaking change would arrive.

The API's version is the first part of every path: `/v1`.

## What can change in v1

These changes can arrive in v1 at any time, and each is listed in the [Changelog](https://docs.kosoor.com.sa/changelog.md):

- new endpoints and new resources, with their own permissions;
- new optional request fields and query parameters;
- new fields in replies;
- new error codes;
- new values in fields that name a kind or a channel, such as `createdVia`.

So your client must ignore reply fields it does not know, and handle a value it does not know, for example by treating an unknown `createdVia` like `unknown`.

## What does not change in v1

- An existing field keeps its name, its type and its meaning.
- An error `code` keeps its meaning. Branch on `code`; `message` is text for people and can be reworded or translated at any time.
- A request that works today keeps working.

Requests stay strict: a field or query parameter that an endpoint does not know is refused with `400 unknown_parameter`. A new optional field becomes accepted only once it is released and listed in the changelog.

## A breaking change

A change that would break a working client, such as removing or renaming a field, comes as a new version with its own path prefix, such as `/v2`.

Source: https://docs.kosoor.com.sa/versioning