# API versioning

How we approach API compatibility, breaking changes, and beta releases.

Our aim is to improve the aclipp API without making existing integrations needlessly change. This guide sets out our current approach to compatibility and early-access features. It is a starting policy that we will refine as the API develops, not a promise of a fixed release schedule or support lifetime.

## Versions and compatibility

The public REST API currently uses `/api/v1`. The version in the path identifies the API contract, not every deployment of the service. Fixes and compatible additions can ship within that version.

For stable endpoints, our principle is that a valid integration should continue to work when we make a compatible change. Examples include adding an endpoint or adding an optional request parameter whose default preserves existing behavior. Clients should also tolerate additional response fields rather than rejecting a response because it contains an unfamiliar property.

Compatibility depends on behavior as well as JSON shape. Removing or renaming a field, making an optional input required, changing a field's type, or changing the meaning of an existing operation can break an integration. Adding values to an enum can also affect clients with exhaustive handling; we do not assume every addition is harmless.

## Breaking changes and deprecation

For a planned breaking change to a stable contract, our approach is to introduce a new API version or a replacement operation and provide a migration path. We aim to give advance notice and explain what is changing, how to migrate, and when the old behavior will be retired.

We have not set a universal notice period or a guaranteed lifetime for each API version. Those details will be specified with the relevant change. Urgent security or data-protection fixes may require faster action.

## Release stages

Availability and stability are different questions. A feature can be available to everyone while its contract is still evolving.

| Stage                                    | Availability                                    | What to expect                                          |
| ---------------------------------------- | ----------------------------------------------- | ------------------------------------------------------- |
| <ApiBetaBadge stability="closed-beta" /> | Selected organizations with the feature enabled | Early feedback; inputs, outputs and behavior may change |
| <ApiBetaBadge stability="beta" />        | Generally available                             | Broader use and feedback; the contract may still change |
| Stable, no badge                         | Available under the usual access rules          | The compatibility and migration approach above applies  |

These are the same badges shown beside endpoint titles in the [API reference](/docs/api-reference). Hover over a badge or focus it with your keyboard to read its explanation.

Closed-beta and beta endpoints may change without a new API version or the advance migration period intended for stable endpoints. Allow for adjustments when integrating them. Moving from closed beta to beta broadens availability; it does not make the contract stable.

## Availability and permissions

“Generally available” does not mean unrestricted access. Authentication, credential scopes, member permissions and project restrictions still apply. See [Authentication and scopes](/docs/authentication).

A closed-beta endpoint may be documented before it is enabled for your organization. A new API key or wider scopes do not enable the feature. An otherwise authorized request to a disabled feature returns HTTP `403` with `FEATURE_UNAVAILABLE`; the error's `availability` field identifies the resource and stage. Missing credentials or permissions may be rejected before the feature check.

## MCP tools

MCP tools follow the same stability principles as their underlying API operations. Tool descriptions and discovery metadata identify `closed-beta` and `beta` tools. Closed-beta tools are offered only to enabled organizations, with access checked again on each call.

The MCP protocol version describes how a client communicates with the server. It is separate from the REST API version and does not freeze the inputs or behavior of a beta tool. See the [MCP guide](/docs/mcp) for connection details.