Versioning policy

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:

• 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:

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, also served by the API at /openapi.json. Our tests check that every route the server registers matches it, so the API reference always describes what the server actually does.