> For the complete documentation index, see [llms.txt](https://gitbook-docs.coinmetrics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook-docs.coinmetrics.io/api-reference/backward-compatibility.md). # Backward Compatibility Policy This policy says what an integration built against the Coin Metrics API may rely on. It exists so that a client written today keeps working as the API changes, and so that the changes we consider routine are predictable rather than surprising. The API is versioned with [Semantic Versioning](https://semver.org/), as `major.minor.patch`. Backward incompatible changes raise the major number, backward compatible changes raise the minor number, and backward compatible fixes raise the patch number. ## Versions Major versions run in parallel, and choosing one is up to you. New major versions are published alongside existing ones, so clients of an existing version are unaffected by a release. Old major versions may be deprecated and eventually removed on a long-term schedule that gives clients time to migrate. Minor and patch releases replace the previous minor or patch within the same major version, and the version they replace stops being reachable. Every major version carries a stability label, and the label determines how much of this policy applies. | Label | What it means | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Stable** | Covered by this policy in full. Backward incompatible changes are not made. Use a stable version in production. | | **Unstable** | Fully tested, usable, and documented, but not covered by the compatibility rules below. It can change without warning. Intended for evaluating new features, not production. | | **Development** | May change at any time and may be incomplete or broken. Avoid it. | A new major version is normally published as unstable, then becomes permanently stable after a period of stabilization. `v4` is stable, and is the version this reference documents. ## What may change in a minor or patch release A change is backward compatible when a client built against an earlier version of the same major version still works. Each item below is something we may do at any time, paired with the assumption you therefore should not encode.
We maySo do not
Add an endpointRely on a path or method being absent
Add a field to an existing responseReject or fail on unrecognized fields
Add an optional request parameter, where omitting it preserves the previous behaviorSend parameters an endpoint does not document. They are ignored now, but may later be interpreted
Make a required parameter optionalDepend on a request being rejected for omitting it
Add a value to an enum-typed parameterAssume the documented set of values is closed
Reword any human-facing string, including asset and metric names, descriptions, and error messagesBranch on message text. Branch on the stable fields instead, such as an error type
Add, remove, or change which assets, metrics, markets, and exchanges are availableHard-code a resource list. Read it from reference data and catalog endpoints at run time
Fix behavior that was unusable enough that no working client could have depended on itRely on a defect
{% hint style="warning" %} Which resources exist is not part of the API interface and is not covered by this policy. Assets, metrics, and markets are added and removed continuously, so a client that hard-codes them will break on a routine data change rather than on an API release. {% endhint %} ## What requires a new major version These changes are made only in a new major version, or in one already labeled unstable or development. On a stable major version, you can assume they will not happen. * Renaming or removing an endpoint. * Removing a required request parameter. * Making an optional request parameter required. * Renaming a request parameter, or changing its meaning. * Renaming or removing a value of an enum-typed parameter, or changing its meaning. * Removing a fixed-name field from a response. * Changing the structure of a response. ## Emergency changes Changes normally follow this policy. Breaking changes may still be made without a new major version where they are necessary to keep Coin Metrics services running, for security reasons, or where following the policy is not feasible. That includes introducing or changing rate limits, applying limits to a specific API key, and disabling a method or feature immediately. This policy itself may also change. Such changes are rare, are made only after assessing the effect on clients, and come with as much advance notice as circumstances allow. ## Related * [API Conventions](/api-reference/api-conventions.md): the cross-cutting behavior this policy governs, including the stable error `type` values. * [Rate limits](https://docs.coinmetrics.io/api-reference/rate-limits): the current limits, which the emergency clause above allows us to change. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook-docs.coinmetrics.io/api-reference/backward-compatibility.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.