API Versioning

Clara maintains multiple API versions simultaneously so you can integrate at your own pace without forced migrations.

​

Current versions

​

What constitutes a breaking change

Clara considers these breaking changes — they will never happen within a version:

• Removing an existing field from a response
• Changing a field’s data type
• Removing an endpoint
• Changing authentication requirements

These are non-breaking and may happen without a version bump:

• Adding new optional fields to responses
• Adding new optional query parameters
• Adding new endpoints
• Improving error messages

​

Deprecation policy

When Clara deprecates a version:

1. A deprecation notice is published in the Changelog with at least 6 months’ notice
2. The version remains functional throughout the deprecation period
3. A migration guide is provided before end-of-life

v1 and v2 are currently not deprecated — they will continue to receive security fixes.

​

Version coexistence

All three versions share the same authentication (mTLS + OAuth 2.0). You can call v2 and v3 endpoints in the same integration using the same credentials — version is determined by the URL path (/api/v2/... vs /api/v3/...).

​

Selecting a version

Use the v3 tab on any API reference page to see the current interface. If a service is not yet available in v3, the page will indicate which version to use instead.