---
title: "API versioning"
description: "Stability guarantees, breaking-change rules, and deprecation notice period"
canonical: "https://onecheckout.ai/docs/versioning"
last-updated: "2026-08-24"
---
# API versioning and deprecation policy

The canonical base path is /api/v1. This page states what we guarantee about changes to it, how deprecations are signalled in the response itself, and how much notice you get before anything is removed.

Canonical HTML version: https://onecheckout.ai/docs/versioning
Machine-readable API description: https://onecheckout.ai/openapi.json

## Current version

The current major version is v1. Every documented endpoint lives under /api/v1/. Use that prefix for new integrations.

The machine-readable description of the whole surface is at /openapi.json, and every /api/* response carries a Link header with rel="describedby" pointing at it.

## What counts as a breaking change

We treat a change as breaking if a correct client could stop working because of it. Breaking changes ship under a NEW version prefix. They are never applied in place to /api/v1.

- `Breaking (new version prefix)`: Removing or renaming a field or endpoint; adding a required request field; narrowing an accepted value; changing a field's type; changing the meaning of an existing status code or error code.
- `Additive (ships within v1)`: New endpoints; new OPTIONAL request fields; new response fields; new enum values in a field documented as open-ended; new error codes for genuinely new conditions. Parse responses leniently and ignore unknown fields.

## How deprecation is signalled

A deprecated endpoint keeps working for the whole notice window. While it is deprecated, its responses carry these headers, so a client can detect the migration without reading this page.

- `Deprecation: true`: RFC 8594. This exact resource is deprecated.
- `Sunset: Sun, 21 Feb 2027 00:00:00 GMT`: RFC 8594. The instant after which the endpoint may stop responding. Treat it as a hard deadline.
- `Link: <...>; rel="successor-version"`: The URL to migrate to. In the common case this is the same path under the current version prefix, so migration is a string replacement.

## Notice period

Deprecated endpoints get at least six months between the deprecation notice and the sunset date.

The currently deprecated set is the older unversioned /api/... paths, deprecated on 2026-08-21 and scheduled for removal on 2027-02-21. They resolve to the same implementation as their /api/v1/ equivalents, so migrating is a prefix change with no behavioural difference.

## What an agent should do

Check for a Sunset header on responses you depend on. If one is present, follow the rel="successor-version" Link and switch to that URL before the date. If you cannot act autonomously, surface the date to a human rather than waiting for the endpoint to start failing.

Errors share one envelope across the whole API: { ok: false, error: { code, message, hint, documentation } }. Branch on error.code, not on the human-readable message, which may be reworded at any time.

## See also

- API reference: https://onecheckout.ai/docs (Markdown: https://onecheckout.ai/docs.md)
- Gallery Submissions API: https://onecheckout.ai/docs/gallery-api (Markdown: https://onecheckout.ai/docs/gallery-api.md)