# Versioning & Release Process

## Versioning and breaking changes

When consuming our API, **be sure to prefix the API URL with a version number**. For example, the base URL of version 1 would be `v1.api.carbonmark.com`.

Any changes that we make to an API version are guaranteed to be backwards compatible. However, if you omit the version prefix ([`api.carbonmark.com`](http://api.carbonmark.com)) **your application will be exposed to breaking changes** because [api.carbonmark.com](http://api.carbonmark.com) is always routed to the latest major version.

To find the latest version of the API, visit [Quickstart](/carbonmark-api/quickstart.md)or view the REST reference docs at [api.carbonmark.com](http://api.carbonmark.com) with the version prefix omitted. Likewise you can find the REST reference docs for previous API versions by navigating to the base URL for that version.

## Deprecation policy

When a new version of the Carbonmark API is released, we consider all previous versions to be *deprecated* from that date forward. **We can only guarantee that a deprecated version will stay available to existing users for three months**. After the three month deprecation period the version is considered *retired*.

Retired versions are no longer supported, and are likely to become unstable or be removed completely.

Deprecated versions will be maintained to ensure stability and availability, but they will not receive new features or major improvements.

## Canary versions

Occasionally, we will give a customer early access to a feature or improvements via unreleased “canary” or “staging” URLs.

Please note that these URLs do not include guarantees for stability, compatibility or long-term support and may become unstable within weeks or months. Users are discouraged from sharing these URLs externally, and are encouraged to migrate to the next major version as soon as it is available.

## Upgrading

See individual version pages for release notes and other pertinent upgrade information.


---

# Agent Instructions: 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:

```
GET https://docs.carbonmark.com/carbonmark-api/versioning-and-release-process.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.