# Versioning

The API follows [semantic versioning](https://semver.org/):

- **The major is in the URL.** `/v1/` is major version 1. A change that could break a working integration never ships inside `v1`; it ships as `/v2/`.
- **The full version is `MAJOR.MINOR.PATCH`**, for example `1.6.0`: `info.version` in [`/openapi.yaml`](https://docs.creator-guard.com/openapi.yaml), the heading of each [changelog](https://docs.creator-guard.com/changelog/) entry and the `X-API-Version` header of every answer. Log it with your requests.
- **The numbers continue** after `1.3.0`, the last version of the retired partner endpoint `POST /api/partner/v1/leads`: this API started at `1.4.0`. That endpoint's history is at the end of the [changelog](https://docs.creator-guard.com/changelog/).

## What changes the version

| Change | Version |
|---|---|
| Clearer docs; a fix that makes the API do what the docs already said | **PATCH** (`1.6.0` → `1.6.1`) |
| Something added: an optional request field, a response field, an endpoint, a scope, an error code for a new situation | **MINOR** (`1.6.0` → `1.7.0`) |
| Stricter validation within v1 (below) | **MINOR** with a **Tightened** entry |
| Anything that can break a working integration | **new major** (`/v2/`) |

Breaking: removing or renaming a field, a new *required* request field, accepting fewer values for a field, removing an error code or status, a different code for an existing situation, a changed type, authentication or base URL.

Read answers tolerantly: ignore fields, headers and enum values you do not know, and treat an unknown `error.code` by its HTTP status. That is what lets us add things within v1.

## Beta

The platform and the API are in **beta**. The rules on these pages are binding, and the contract check below still blocks breaking changes inside `/v1/`. What beta means: features arrive often, and validation can be tightened without notice.

## Stricter validation within v1

Sometimes the API accepts input it cannot handle well. Rejecting it is stricter, but it protects your data rather than changing what a correct integration sends. Such a change ships as a **MINOR** release and is **effective at release**. Its changelog entry under **Tightened** says exactly what is now rejected and with which error; there is no separate email.

The same applies, rarely, to data protection on the answer side: a response field may become `null` in situations where we may no longer show it (for example `creator_name` on offers before payment, 1.11.0). The field stays in every answer; the spec marks it with `x-nullable-since` and the **Tightened** entry says when it is `null`.

## API Terms of Use

The legal rules for using the API are the [API Terms of Use](https://docs.creator-guard.com/legal/api-terms/), a versioned agreement of its own (`api_terms`), separate from this contract versioning. A new version is announced with the event `agreement.published` and in the changelog. A material change that is worse for you takes effect **30 days** after we publish it; a change required by law, or needed for security or to stop abuse, takes effect on publication. Accepting the terms is described under [Authentication → API Terms](https://docs.creator-guard.com/authentication/#api-terms).

## Retiring a major

When `/v2/` goes live, `/v1/` stops on the same day: every request answers [`410 version_sunset`](https://docs.creator-guard.com/errors/#version_sunset), with `Deprecation`, `Sunset` and `Link` headers pointing to the migration guide. There is no notice period, so watch the [changelog](https://docs.creator-guard.com/changelog/).

## How we keep to this

The published contract is checked automatically before every release against the last recorded version: an addition needs a MINOR version, stricter validation needs a **Tightened** entry, and a breaking change cannot be released under `/v1/` at all.
