Clarra Public API — Versioning

Clarra's Public API is versioned so we can add new capabilities over time without breaking integrations that already work.  API versioning is designed to preserve backward compatibility while introducing new features, enhancements, and improvements without disrupting existing integrations.  This guide explains how versioning works, how to choose a version, and what happens if you don't specify one.

Versioning Strategy

Clarra's API versioning strategy is built around two principles:

• Default version (v1) — the stable, broadly supported version intended for existing integrations.
• Versioned endpoints (v2, v3, …) — introduce new features, enhancements, and performance improvements, while remaining compatible with previous versions.

Clients are encouraged to migrate to the latest API version to take advantage of new functionality and ongoing improvements.

Default Behavior

If a request does not specify an API version, Clarra automatically processes it using API Version 1 (v1). For example:

GET https://api.clarra.com/api/matters

is equivalent to:

GET https://api.clarra.com/api/v1/matters

This default behavior ensures that existing integrations continue to function without requiring any changes.

Specifying an API Version

To target a specific API version, include the version number in the request URL.

Version 1

GET https://api.clarra.com/api/v1/matters

Version 2

GET https://api.clarra.com/api/v2/matters

Each API version is maintained independently and may introduce new endpoints, request or response model changes, additional fields, or new functionality.

Backward Compatibility

Clarra is committed to maintaining backward compatibility wherever possible:

• Existing API versions continue to function as documented.
• Enhancements and new features are introduced in newer API versions, not retrofitted into older ones.
• Breaking changes are released only as part of a new major API version.
• Existing integrations continue to operate until a version is officially retired.

Deprecation Policy

When an API version is superseded, it is marked as Deprecated and remains available for a defined transition period so customers have sufficient time to migrate.

During the deprecation period:

• The deprecated version continues to operate as before.
• Documentation clearly indicates the deprecation status and the recommended replacement version.
• Customers are encouraged to migrate to the latest supported version.
• Advance notice is provided before a deprecated version is retired.

Best Practices

• Always specify the API version explicitly in production applications — never rely on the default.
• Use the latest supported version for all new integrations.
• Review release notes before upgrading to a newer version.
• Test integrations against a new API version in a staging environment before deploying to production.

Note: Requests that omit an API version are automatically routed to API Version 1 (v1) to preserve backward compatibility with existing integrations.

Frequently asked questions

Do I have to upgrade to v2?
No. V1 continues to work. Move to v2 only when you want the extended features it offers.

Will v1 be removed?
Any decision to retire a version will be communicated in advance through Clarra's release notes/changelog, with a migration window. There is no need to change anything today.

What happens if I request a version that doesn't exist for an endpoint?
The API returns an error indicating the request could not be matched to a supported version, along with the versions that are supported for that endpoint.

Can I mix versions across different endpoints in the same integration?
Yes. Versioning is per-endpoint-call, not account-wide — you can call v1 for one endpoint and v2 for another in the same integration.

Quick reference

Base URL:        https://api.clarra.com

Versioned path:  /api/v{version}/{controller}/{action}

Default version: v1 (used automatically if none is specified)

Specify via:     URL segment (/api/v2/...), query string (?version=2.0), or header (x-api-version: 2.0)

For endpoint-by-endpoint details — including which fields and features are new in each version — see the interactive API reference at Clarra API Document.