Versioning and deprecation - cloro
Guides
Versioning and deprecation
How the cloro API is versioned, which changes ship without warning, how a deprecation is announced, and what the Deprecation and Sunset headers tell you.
The version is in the URL path. Every endpoint lives under
/v1/
, and there is no version header or query parameter to set.
Navigate to header: What can change inside a version 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 recognize.
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.
Navigate to header: How a deprecation is announced 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 ) |
| Sunset | When the endpoint stops responding ( RFC 8594 ) |
| 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
/
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.
Navigate to header: Checking programmatically Checking programmatically
The
OpenAPI specification
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.
Was this page helpful?
Ask a question...
Navigate to header: What can change inside a version