Skip to main content

API Versioning Policy

This document is an overview of how we govern the Clio Platform API versioning.

Versioning Your API Requests​

  • The Clio Platform API uses date-based versioning in the format YYYY-MM-DD.
  • To make a versioned request, include the X-API-Version header in your API request with a valid date value.
  • Clio recommends using versioned requests when adopting new API behavior so you can test changes before they become the default.
  • An unversioned API request will return a response from the stable version of the API. See "Stable API Behavior" below for more information.
  • Requesting an invalid version format will be treated as an unversioned request.
  • The special value unstable can be used to access the latest API behavior, which is useful for testing upcoming changes.

Stable API Behavior​

  • Unversioned API requests return the stable version of the API. Existing integrations will continue to work without modification.
  • When a breaking change is released as a new dated version, unversioned requests continue to return the previous (stable) behavior.
  • After the deprecation period (see "Version Support and Deprecation" below), the breaking change becomes part of the stable API.

Releasing New Versions​

  • Backwards-incompatible changes to the API are always released as a new dated 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 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 API changelog.

Version Support and Deprecation​

  • Dated versions are supported for 3 months after release. After the 3-month deprecation period, expired versions automatically adopt the newer behavior.
    • For example: If version 2025-06-15 introduces a breaking change, you can use X-API-Version: 2025-06-15 to adopt the new behavior immediately. After September 15, 2025, the change becomes part of the stable API.
  • Requesting an expired version will not return an error. Instead, version checks will return the newer behavior as if the version was current.

Exceptions​

  • In rare cases (such as changes to firm security settings within Clio, critical product bugs, or legal, security, and privacy concerns), Clio reserves the right to change any of the timelines stated above, including:
    • Applying breaking changes to the stable API without the standard deprecation period
    • Shortening the support window for a specific version
    • Applying backwards-incompatible changes immediately across all versions.
  • Clio will make reasonable efforts to provide advance notice of these types of changes via email and the API changelog.