> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofage.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and deprecation

> What the ProofAge API version /v1 promises, which changes are breaking and which are not, how much notice a breaking change gets and how that notice is given.

The API version is part of the path: `https://api.proofage.net/v1`. This page says what stays stable within `v1` and how changes reach you.

## What /v1 promises

Within `v1`, ProofAge makes only non-breaking changes to the API and to the [decision webhook](https://docs.proofage.net/api-reference/webhook-decision.md) unless the notice below has been given. A request that works today keeps working, and the fields you read today keep their names, types and meaning.

## Breaking changes

These need notice:

* removing or renaming an endpoint, a request field, a response field or a webhook field;
* removing or renaming a value of an enumeration, such as a status or a reason;
* changing a field's type or meaning;
* tightening validation, so that a request accepted today is refused;
* changing a default, so that the same request behaves differently.

## Non-breaking changes

These can ship at any time, and your integration must cope with them:

* new response or webhook fields: ignore keys you do not know;
* new optional request parameters and headers;
* new values of an enumeration, such as a new verification status, decision reason or error code: handle a value you do not know, for example as "needs a person to look";
* new endpoints;
* new webhook event types;
* a different order of keys in a JSON object, and a different `message` text for an error (read the `code`, not the `message`).

## Notice

A breaking change to `v1` is announced at least **six months** before it takes effect, through:

* an entry in the [changelog](https://docs.proofage.net/changelog/2026-11.md);
* an e-mail to the administrators of every workspace that uses the affected call;
* `Deprecation` and `Sunset` response headers on the affected calls during the notice period, so a client can log them.

A change needed to fix a security vulnerability or to comply with the law may get shorter notice; the changelog says why.

## New security requirements

A new security requirement may become the default for **new** workspaces before existing ones are asked to adopt it. Existing workspaces keep working as they do until their owner turns the requirement on. [Timestamped signatures](https://docs.proofage.net/getting-started/api-authentication.md#the-timestamp) work this way: every workspace accepts them, existing workspaces still accept a signature without a timestamp, and a workspace's owner decides when to require them.

## SDKs

The [server SDKs](https://docs.proofage.net/integration/sdks.md) follow semantic versioning. Before 1.0, a minor release may change the SDK's own interface; it never stops supporting a `v1` call that the API still accepts. Update them regularly so new optional features reach you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.