API Versioning Policy

This document is an overview of how we govern our APIs. Information about all currently supported API versions can be found in the API documentation.

Versioning Your API Requests

API v4 supports both versioned and unversioned API requests.
To make a versioned request, you must include the X-API-VERSION header in your API request. (See the API Documentation for more information)
Clio strongly recommends versioning your API requests for predictability and stability in your application.
An unversioned API request will return a response from the default version of the API - see “Default API Version” below for more information.
Requesting an invalid version of the API will return a 410 GONE error.
Requesting a deprecated version of the API will return a 410 GONE error. See “Version Support and Deprecation” below for more information.

Clio designates one default version of the API at a time. Unversioned API requests are treated as a request to the default version of the API. (See the “Minor Versions” section of the documentation to see which version is currently the default.)
Clio will announce any upcoming changes to the default version of the API by email, as well as in the Minor Versions section of the API documentation. Where possible, Clio will provide a minimum of 90 days notice (see the “Exceptions” section below for information).

Backwards-incompatible changes to the API are always released as a new version. These include semantic or structural changes to the API that could cause errors or unexpected behavior in consuming applications.
- Examples include deprecating fields or endpoints, changing the data type of a field, requiring fields that were previously optional, and so on.
Backwards-compatible changes are not versioned; they are made available in all versions of the API immediately upon release. Changes of this type will not impact existing API endpoint behavior.
- Examples include new API endpoints, new optional fields in existing endpoints, new values in enum fields, new endpoint actions, and new API features.
Clio does not have a fixed schedule for releasing new API versions.
New API versions are announced by email and documented in the Minor Versions section of the API documentation. We may announce these changes in the public Slack developers channel as well.
New version announcements will include the date at which the new API version will be designated as the default version. Usually, this will be 90 days after the release of the new version.

Clio will support API versions for a minimum of one year after a new default version is designated. Clio may choose to support older API versions for longer than one year as needed.
- For example: If version 4.0.8 of the API is the default version, and version 4.0.9 is made the default version on March 1, 2022, support for version 4.0.8 is guaranteed until March 1, 2023.
90 days before a version will be deprecated, Clio will provide notice to ecosystem developers via email. Upcoming deprecations will also be documented in the Minor Versions section of the API documentation.
Once a version of the API is deprecated, requests specifying that version will return a 410 GONE error.

In rare and exceptional circumstances—such as changes to firm security settings within Clio, critical product bugs, and legal, security, or privacy concerns—Clio reserves the right to change any of the timelines as stated above, including:
- Ending support for API versions without notice or delay
- Changing the default version of the API
- Applying backwards-incompatible changes to older versions of the API.
Clio will make reasonable efforts to provide advance notice of these types of changes via email, as well as documenting the changes in the Minor Versions section of the API documentation.
If backwards-incompatible changes need to be applied to older API versions, Clio will (when possible) make these changes available in a new API version 90 days before backfilling them.