# Versioning and compatibility

> How the Noptcha API changes - backward-compatible additions in v1, at least 12 months for v1 after a v2, and what clients must tolerate.

Source: https://noptcha.com/docs/versioning/

## Native API (v1)

`/v1` changes only in **backward-compatible** ways. We may at any time:

-   add fields to responses and optional fields to requests;
-   add endpoints;
-   add values to existing fields: error codes, task types, task statuses, families, variants;
-   add task types and compatibility names.

Your client must **ignore unknown fields and accept unknown values**. Do not reject a response because it has a field you do not know, and treat an unknown error code by its HTTP status.

Changes that would break existing clients go into a new version (`/v2`). After `/v2` is released, `/v1` keeps working for **at least 12 months**.

## Compatibility API

The compatibility API has no version: it follows the anti-captcha compatible protocol. New task type names and error codes can be added; existing names keep their meaning.

## What is not covered

-   Error messages (`detail`, `errorDescription`, `error_text`, `error.message`) are for humans and may change; use the codes.
-   [Limits](https://noptcha.com/docs/limits.md) are starting values and may change.
-   Beta task types may change their parameters and behaviour.
-   The sandbox’s answers are fixed per type, but new magic values may be added.

## Machine-readable description

The [OpenAPI description](https://noptcha.com/openapi.json) (also as [YAML](https://noptcha.com/openapi.yaml)) is the reference for field names and types. It is checked against the implementation by automated contract tests.