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...

RFC 9745

RFC 8594

OpenAPI specification

Navigate to header: What can change inside a version

Navigate to header: How a deprecation is announced

Navigate to header: Checking programmatically