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

# Versioning and deprecation

> How the cloro API is versioned, what changes without warning, and how a deprecation is announced.

The version is in the URL path. Every endpoint lives under `/v1/`, and there is no version header or query parameter to set.

## What can change inside a version

Changes inside `/v1/` are additive:

* new endpoints
* new optional request fields
* new fields in a response body

A client has one obligation in return: **ignore response fields you do not recognise.** A parser that rejects unknown fields turns a routine addition into an outage on your side.

These never change inside a version:

* the meaning or type of an existing field
* an existing field becoming required, or disappearing
* an error `code` string for a given failure
* the path of an existing endpoint

A change of that kind gets a new version path (`/v2/`). Existing paths are not repurposed.

## How a deprecation is announced

A deprecated endpoint says so in its own responses, so a client learns about it from a call rather than from a changelog nobody reads:

| Header                          | Meaning                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| `Deprecation`                   | When the deprecation took effect ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html))   |
| `Sunset`                        | When the endpoint stops responding ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) |
| `Link` with `rel="deprecation"` | Documentation for the replacement                                                            |

There is a **minimum of six months** between the `Deprecation` date and the `Sunset` date on any generally available endpoint.

```http theme={null}
HTTP/1.1 200 OK
Deprecation: @1767225600
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://cloro.dev/docs/api-reference/endpoint/monitor-chatgpt>; rel="deprecation"; type="text/html"
```

Nothing is deprecated today, so no live endpoint carries these headers.

## Checking programmatically

The [OpenAPI specification](https://cloro.dev/openapi.json) is the authoritative list of what exists in the current version. Log the `Deprecation` and `Sunset` headers alongside your other request metadata — that way an endpoint you depend on cannot be retired without it showing up in your own logs first.