# Versioning

URL: https://submitator.com/docs/versioning

> v1 has been generally available since 2026-10-07. Breaking changes only ever arrive in a new version, /v2, with 6 months of overlap.

The version is part of the path: every route starts with `https://api.submitator.com/v1`. There are no version headers and no dated versions.

## v1 is generally available

v1 has been generally available since 2026-10-07, and the policy on this page applies to it. `GET /openapi.json` reports `info.version` `1.0.0` and returns the operations the reference shows.

The [changelog](https://submitator.com/docs/changelog) dates every change since v1 opened on 2026-10-06.

## Breaking changes go to /v2

A change that can break working code only ever ships in a new version, such as `/v2`. When it does:

- `/v1` keeps working for 6 months after `/v2` is released.
- Responses from `/v1` carry `Deprecation` and `Sunset` headers with the dates.
- The owner of every account with a key gets an email, and the dated [changelog](https://submitator.com/docs/changelog) lists each change.

## Changes that are not breaking

These can arrive in v1 at any time, so build your integration to accept them:

- New operations, new optional parameters and new fields in responses.
- New values in the open lists: listing `reason`, `action.code`, `readiness.missing`, `unlocks[].requirement`, the badge recipe's `platform` and `language`, and a delivery's `last_attempt.error`.
- New event types. Answer 2xx to a webhook of a type you do not know.
- New wording in any `message`. Branch on `code`, never on the text.

Ignore the fields you do not use, and handle a value you do not know: for an unknown `action.code`, show `client_message`, or a general prompt when it is `null`.