---
title: Versioning and compatibility
description: The Clipia API evolves within one version, /v1 — which changes count as compatible, what goes in the changelog, deprecated fields and SDK versions.
icon: GitBranch
---

The public API lives at `/v1/*`, and that is the only current version. We evolve the contract without changing the number and record notable changes in the [changelog](/en/docs/changelog). The versioning policy is still being refined: there are no notice periods for changes and no separate path version yet.

## What we consider compatible

These changes ship without notice and do not change the path version. A client must tolerate them without code changes:

- new endpoints and new optional request parameters;
- new fields in responses, in the `output`, `warnings` and `error` objects;
- new `warnings[].code` values and new error `code` values within existing HTTP statuses;
- new models in the catalog and new `input` parameters on models, described in the model's `input_schema`;
- changes to `message` text, which is meant for humans.

Two rules for an integration follow: ignore unknown fields, and branch on `code` and `status`, never on the message text. Clients that wait for a terminal status depend on the complete list of `status` values, so we treat a new value as a breaking change, along with a new error `type`.

## Breaking changes

Removing or renaming an endpoint, field or parameter, changing a field's type or meaning, removing a `status` value or an error code, or changing the authentication scheme counts as breaking. We call out such a change in the [changelog](/en/docs/changelog).

## Deprecated fields [#deprecated]

A field is marked deprecated when it no longer carries meaning but stays in responses for compatibility. Removing a deprecated field is a breaking change.

| Field | Where | Now | Use instead |
|-------|-------|-----|-------------|
| `queue_position` | responses of [submit](/en/docs/api-reference/submit) and [status](/en/docs/api-reference/status) | always `0`: the queue position is not computed | `status` and `progress` |

## SDK versions

The official clients, TypeScript [`clipia-ai`](/en/docs/sdk/typescript) on npm and Python [`clipia`](/en/docs/sdk/python) on PyPI, follow semver and are released with the same number: a new field, option or method is a minor release, a fix is a patch, a removal or a type change is a major release. The history lives in the package changelogs and in the [portal changelog](/en/docs/changelog). The MCP server version is tracked separately and is visible in its metadata.

## Service status [#status]

The public API has no separate status page and no service level agreement (SLA) today. For questions about outages, contact support: support@clipia.ai and Telegram [@clipia_support](https://t.me/clipia_support). If a request returns `503 service_unavailable` or `500 internal_error`, retry it with a growing pause following the [Errors](/en/docs/api-reference/errors) page; credits for a generation that did not start are not charged.