# Versioning

What can change within v1, what counts as a breaking change, and how long old versions are supported.


The API version is in the URL (`/api/v1`) and in the `API-Version` response header.

## Additive changes inside v1

These can ship at any time without a new version:

- New endpoints.
- New optional request fields.
- New fields in responses.
- New error codes.
- New values in lists that are documented as open, such as `record_type`.

Write your client to ignore unknown fields, and to handle an unknown error code by its HTTP status.

## Breaking changes mean a new major version

These only ship in a new version, `/v2`:

- Removing or renaming a field or an endpoint.
- Changing a field's type.
- Making an optional field required.
- Changing authentication or error behavior.

## Deprecation

When v2 ships, v1 keeps running for at least 12 months. Deprecated responses carry `Deprecation` and `Sunset` headers so you can detect them in code.

## Changelog

Every API change is listed, with its date, in the [API changelog](/developers/changelog). It is separate from the product changelog.

## Current limits of v1

A few fields exist in the shapes but are not filled in yet, so treat them as placeholders. For example, `date` and `record_id` on events are `null`; use `year`. When a field starts carrying data, that is an additive change and will be in the changelog.

- Creating a family (`POST /families`) needs one or two `partner_ids`; `child_ids` are optional, and a family needs at least two people in total. The API never creates placeholder parents, so to record siblings whose parents are unknown, create a parent first. If an extra child cannot be attached, the `201` response carries a `warnings` array naming it; the family itself was created.
- People have a `created_at` but no `updated_at` in v1. To detect changes to a person, compare the fields you care about.

Canonical: https://kleiobase.com/developers/docs/versioning