CertuAI API versioning and deprecation policy

This policy covers the CertuAI REST API (/api/v1) and the MCP server, which run the same tools. It says what can change in v1, how a breaking change is shipped, and how you are told before anything is removed.

Current version

• The current version is v1, in the path: https://certuai.com/api/v1. The version is part of the URL, not a header.
• The machine-readable form of this policy is the x-deprecation-policy object in /openapi.json.

What can change in v1

• Changes to v1 are additive only: new endpoints, new tools, new optional parameters and new fields in responses.
• An integration should ignore response fields it does not know, so that an additive change never breaks it.

Breaking changes

• Anything that would break an existing integration ships under a new version path, /api/v2, and v1 keeps answering as documented.
• Breaking means, for example: removing an endpoint, a tool or a response field; renaming one; making an optional parameter required; or changing the type or meaning of a field.

Before anything in v1 is removed or changed

• Key owners are notified by email.
• The affected endpoints send the Deprecation header (RFC 9745), with the date the endpoint became deprecated, and the Sunset header (RFC 8594), with the date it stops answering.
• They also send Link: <https://certuai.com/docs/versioning>; rel="deprecation"; type="text/html", pointing to this page.
• The deprecated operation is flagged deprecated: true in /openapi.json, and its 200 response documents the three headers.
• On the MCP server, a single tools/call request to a deprecated tool carries the same headers.

How to stay ahead of a deprecation

• Log or alert on any response that carries Deprecation or Sunset.
• Check deprecated: true in /openapi.json when you regenerate a client.

What a deprecated response looks like

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Deprecation: @<unix-timestamp>
Sunset: <HTTP-date>
Link: <https://certuai.com/docs/versioning>; rel="deprecation"; type="text/html"

The values in angle brackets are placeholders; the real dates come with the notice.

Related

• CertuAI API and MCP docs
• OpenAPI 3.1 spec
• llms.txt
• Connect Claude to CertuAI

Updated 2026-10-08