> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://catena.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server.

# API Stability & Versioning

> **Check**
>
> Catena's API provides clear stability guarantees. Stable endpoints maintain backward compatibility, while provisional endpoints allow us to iterate based on your feedback.

## Endpoint Stability Levels

### Stable Endpoints

Endpoints **without** the  **vial icon** are considered **stable** and production-ready. These endpoints:

* **Maintain backward compatibility** across minor and patch releases
* **Guarantee no breaking changes** without a major version update
* Receive full support, bug fixes, and maintenance

> **Tip**
>
> Use stable endpoints for production applications where reliability and predictability are critical.

### Provisional Endpoints

Endpoints marked with the  **vial icon** are **provisional** and may change based on customer feedback. These endpoints:

* **May introduce breaking changes** in future releases without a major version bump
* Allow us to iterate quickly on new features based on real-world usage

> **Warning**
>
> **The core schema of provisional endpoints is stable, but minor details — such as field names or added fields — may change before it becomes generally available. Backward compatibility is not guaranteed.** Use these endpoints when you want early access to new features and can adapt to changes.

## Breaking Change Policy

### For Stable Endpoints

When breaking changes are unavoidable for stable endpoints, we follow a multi-step deprecation process:

#### Deprecation Notice

Fields and endpoints are marked as deprecated in the API documentation and OpenAPI specification. We provide clear guidance on alternative solutions.

#### Telemetry Monitoring

We monitor API usage patterns via telemetry to understand impact and ensure customers have migrated to new alternatives before removal.

#### Major Version Release

Deprecated fields and endpoints are removed only in the next major version release (e.g., v2 → v3). The previous version continues to work but becomes unmaintained.

### For Provisional Endpoints

Provisional endpoints may change with shorter notice, but we commit to:

1. **Monitoring usage via telemetry** to understand impact before renaming, replacing, or removing endpoints
2. **Providing migration guidance** when endpoints or field structures change
3. **Giving reasonable notice** whenever possible to minimize disruption

## Versioning Strategy

Our API uses semantic versioning with the format `vMAJOR`:

* **Major version** (e.g., `/v2/`): Introduces breaking changes, removes deprecated features
* **Minor updates**: Add new features, provisional endpoints, or non-breaking enhancements
* **Patch updates**: Bug fixes and performance improvements

> **Note**
>
> The current API version is **v2**. All endpoints are prefixed with `/v2/` in the base URL: `https://api.catenatelematics.com/v2/`

## Stay Informed

Track API changes, new features, and deprecation notices:

* **OpenAPI Specification** - Review endpoint stability markers and detailed schemas
* **Support** - Contact [support@catenaclearing.io](mailto:support@catenaclearing.io) with questions about stability or migration