> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Stability & Versioning

> How to use our API with confidence

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

## Endpoint Stability Levels

### Stable Endpoints

Endpoints **without** the <Icon icon="vial" /> **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.
</Tip>

### Provisional Endpoints <Icon icon="vial" />

Endpoints marked with the <Icon icon="vial" /> **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.
</Warning>

## Breaking Change Policy

### For Stable Endpoints

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

<Steps>
  <Step title="Deprecation Notice" icon="triangle-exclamation">
    Fields and endpoints are marked as deprecated in the API documentation and OpenAPI specification. We provide clear guidance on alternative solutions.
  </Step>

  <Step title="Telemetry Monitoring" icon="chart-line">
    We monitor API usage patterns via telemetry to understand impact and ensure customers have migrated to new alternatives before removal.
  </Step>

  <Step title="Major Version Release" icon="code-branch">
    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.
  </Step>
</Steps>

### 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/`
</Note>

## 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