# Versioning policy

> How the K-Agent API evolves — /v1 changes only additively, the K-Agent-Version header, and what your client should tolerate.

You build on K-Agent once and it keeps working. The API version is in the path, `/v1`, and **`/v1` only changes in additive ways**.

## What can change within `/v1`

These are additive and can ship at any time, without notice beyond the [changelog](/docs/en/reference/changelog/):

- new endpoints;
- new optional request fields and parameters;
- new fields in responses and event payloads;
- new **values** in open enums (for example a new `outcome`, `reason_type` or `channel`);
- new event types on streams and webhooks;
- new error codes and warnings.

These will **not** happen within `/v1`: removing or renaming an endpoint or field, changing a field's type or meaning, making an optional field required, or changing an error code you already receive. Such changes would come with a new major version, announced well in advance.

## Write tolerant clients

- **Ignore fields you don't know.** Don't fail when a response or event has more fields than you expect.
- **Handle unknown enum values.** Treat an unknown `outcome` or `status` with a sensible default instead of crashing. In the OpenAPI contract, open enums are declared as `type: string` with an `x-enum-values` list of today's values.
- **Ignore unknown event types** on streams and webhooks.
- **Branch on error `code` and HTTP status**, never on the human-readable `message`, which is localized and may be reworded.

## The `K-Agent-Version` header

Pin the behavior your integration was written against with a dated header:

```text
K-Agent-Version: 2026-10-06
```

- `2026-10-06` is the current — and first — version. A request without the header uses it.
- The value you send is echoed in every response.
- An unknown value returns `400 invalid_api_version`.
- Dated versions are how we would introduce a behavior change that is not purely additive, without breaking clients that pinned an earlier date.

## Deprecation and sunset

If an endpoint or field is ever retired, responses that use it carry the standard `Deprecation` header and a `Sunset` header with the date it stops working, and the changelog says what to use instead. These headers are reserved today: nothing in `/v1` is deprecated.

## The contract

The machine-readable contract is the OpenAPI 3.1 document at [`/docs/openapi.yaml`](/docs/openapi.yaml), also served by the API at `/openapi.json`. Our tests check that every route the server registers matches it, so the [API reference](/docs/en/api/) always describes what the server actually does.