---
title: Toyoni API versioning and deprecation policy
description: Major-version compatibility, deprecation notices, and Sunset commitments for Toyoni's public API.
canonical: https://toyoni.com/api-versioning.md
last_updated: 2026-08-22
---

# Toyoni API versioning and deprecation policy

The current Toyoni public API contract is major version `1`. Clients may send
`X-API-Version: 1`; omitting that request header also selects version 1. Every API
response returns the selected major version in `X-API-Version`.

## Compatibility

Toyoni may add optional response fields, new endpoints, or new optional parameters within
major version 1. Existing fields do not change type or meaning within that major version.
Clients should ignore response fields they do not recognize.

## Deprecation

Toyoni will announce a breaking-version deprecation in this document and on the
[developer documentation](https://toyoni.com/developers/). Affected API responses will
also carry a standard `Deprecation` header with the announcement date and a `Link` header
pointing to the replacement documentation.

## Sunset

Toyoni will publish a `Sunset` response header with the retirement date at least 180 days
before a breaking API version is removed. The version remains available throughout that
notice period. If no `Deprecation` or `Sunset` header is present, major version 1 is active
and no retirement has been announced.

## Errors during migration

An unsupported major version returns `application/problem+json` with a stable `code`, a
human-readable `detail`, and a concrete `resolution`. The live contract is always
available at [openapi.json](https://toyoni.com/openapi.json).