---
title: "API Versioning"
description: "Learn best practices for API versioning to manage changes, ensure stability, and support developers over time."
url: "https://apipartners.mosaicinsurance.com/guides/publish-apis/versioning"
image: "https://apipartners.mosaicinsurance.com/_og/d/c_Ocean.takumi,title_API+Versioning,description_~TGVhcm4gYmVzdCBwcmFjdGljZXMgZm9yIEFQSSB2ZXJzaW9uaW5nIHRvIG1hbmFnZSBjaGFuZ2VzLCBlbnN1cmUgc3RhYmlsaXR5LCBhbmQgc3VwcG9ydCBkZXZlbG9wZXJzIG92ZXIgdGltZS4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiM4MjUwRkYifX19,p_Ii9ndWlkZXMvcHVibGlzaC1hcGlzL3ZlcnNpb25pbmci,s_NmfTALpAqWDnwvLQ.png"
---

## API Versioning

Learn best practices for API versioning to manage changes, ensure stability, and support developers over time.

## [Why API Versioning Matters](#why-api-versioning-matters)

API versioning allows your platform to evolve without breaking existing integrations. As APIs grow, changes to request formats, response structures, or business logic are inevitable. Versioning ensures that developers can continue using stable APIs while migrating to newer versions at their own pace.

A clear versioning strategy improves developer trust, reduces support overhead, and enables long-term platform scalability.

## Explore our APIs

Connect, create, and innovate with our easy-to-use APIs.

[Start building](https://apipartners.mosaicinsurance.com/apis)

### [The Trident API Version Pipeline](#the-trident-api-version-pipeline)

Trident APIs does not use URI-based versioning (there is no `/v1/` in any path). Instead, each contract is published to this portal under one of three named versions, matching the stage it has reached:

-   **beta** — early-access changes, published for review before they progress further. Corresponds to the sandbox environment.
-   **stable** — the validated contract used to develop and confirm integrations. Corresponds to the preprod environment.
-   **live** — the contract currently running in production.

A change typically progresses `beta` → `stable` → `live` as it is validated at each stage. You do not choose an environment yourself — your API key determines which environment your traffic is routed to, and `stable`/`live` normally carry the same contract. Occasional short-lived differences (for example, a hotfix reaching `live` before `stable`) are recorded in the [Release Notes](https://apipartners.mosaicinsurance.com/guides/publish-apis/release-notes), which show rollout status per version.

### [When to Introduce a New Version](#when-to-introduce-a-new-version)

Not every change requires a new version. A new API version is only created when a **breaking change** is unavoidable.

Common breaking changes include:

-   Removing or renaming request fields
-   Changing response structures or data types
-   Modifying endpoint behavior
-   Changing authentication or authorization rules

Backward-compatible changes, such as adding optional fields, are released directly through the `beta` → `stable` → `live` pipeline and recorded in the [Trident API Release Notes](https://apipartners.mosaicinsurance.com/guides/publish-apis/release-notes) — they do not require a new version.

---

### [Recommended Integration Strategy](#recommended-integration-strategy)

Your API key automatically routes your traffic to the correct environment — integrate once, and let the platform handle routing. Review `beta` only to preview upcoming changes before they progress to `stable`. Check the [release notes](https://apipartners.mosaicinsurance.com/guides/publish-apis/release-notes) before each deployment to confirm whether a change affects your integration, and whether it has reached the tier your key is routed to.