Cyndra API

Versioning and deprecation policy.

What we promise not to change, how you find out when something is going away, and how long you have.

All Cyndra API docs

Versioning

One version in the path.

  • The current version is /api/v1. Every response carries Cyndra-API-Version: 1.0.0.
  • A breaking change ships as a new path prefix. The old prefix keeps working through its deprecation window.
  • Additive changes ship in place: new endpoints, new optional parameters, new response fields. Ignore fields you do not recognise and additive changes will never break you.
  • The unversioned endpoints that predate /api/v1 are deprecated, listed below, and still served until their sunset date.

Deprecation

You will not find out by breaking.

Every deprecated endpoint announces itself on every response, with at least 365 days between the announcement and the switch-off.

$ curl -sI https://www.cyndra.ai/api/blog

Deprecation: Sun, 23 Aug 2026 00:00:00 GMT
Sunset: Mon, 23 Aug 2027 00:00:00 GMT
Link: <https://www.cyndra.ai/api/v1/blog>; rel="successor-version",
      <https://www.cyndra.ai/api-docs/versioning>; rel="deprecation"; type="text/html"
  • Deprecation (RFC 9745): the date the endpoint was deprecated.
  • Sunset (RFC 8594): the date it stops working.
  • Link rel="successor-version": what to move to.
  • Link rel="deprecation": this page.

The same facts are in the OpenAPI document: deprecated operations carry deprecated: true, and info.x-versioning lists every deprecation with its dates and successor.

Current deprecations

What is on the way out.

EndpointDeprecatedSunsetUse instead
/api/blog2026-08-232027-08-23/api/v1/blog
/api/blog/{slug}2026-08-232027-08-23/api/v1/blog/{slug}

FAQ

Versioning questions.

How is the Cyndra API versioned?

In the URL path. The current version is /api/v1, and every response carries a Cyndra-API-Version header. A breaking change ships as a new path prefix, never as a change to an existing one.

What counts as a breaking change to the Cyndra API?

Removing an endpoint or a field, renaming anything, tightening validation, or changing the type or meaning of a field. Adding an endpoint, adding an optional parameter, or adding a field to a response is not breaking: clients must ignore fields they do not recognise.

How does Cyndra signal that an API endpoint is deprecated?

Deprecated endpoints keep working and announce themselves on every response: a Deprecation header with the date it was deprecated (RFC 9745), a Sunset header with the date it stops working (RFC 8594), and Link headers pointing at the successor version and at this policy. They are also marked deprecated: true in the OpenAPI document.

How much notice does Cyndra give before switching an API endpoint off?

At least 365 days between the Deprecation date and the Sunset date.