# Versions

### Specifying API version

The API is versioned using root path versioning in the format `/v{version}` . For example `/v1/transfer` .

### Supported API versions

The following REST API versions are currently supported:

`v0.5` -> [swagger docs](https://api.carbonregistry.com/v0.5/openapi)

`v1` -> [swagger docs](https://api.carbonregistry.com/v1/openapi)

The following REST API versions are deprecated:

`v0` -> [swagger docs](https://api.carbonregistry.com/v0/openapi)

### About API versioning

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:

* removing an entire operation
* removing or renaming a parameter
* removing or renaming a response field
* adding a new required parameter
* making a previously optional parameter required
* changing the type of a parameter or response field
* removing enum values
* adding a new validation rule to an existing parameter
* changing authentication or authorization requirements

Any additive (non-breaking) changes will be available in the newest API version - they could be available in older versions but don't count on it. Additive changes are changes that should not break an integration. Additive changes include:

* adding an operation
* adding an optional parameter
* adding an optional request header
* adding a response field
* adding a response header
* adding enum values

When a new REST API version is released, the previous API version will be supported for at least 6 more months following the release of the new API version, and we expect our integration partners to migrate to a newer version inside this depreciation timeframe. 


---

# 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://documentation.carbonregistry.com/documentation/carbonregistry.com/api/versions.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.