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

# Versioning

> How we version the API, what counts as a breaking change, and how to upgrade safely

## Overview

The API uses **path-based major versioning** and **semantic versions** in the spec:

* **Routing (breaking changes):** `/{api}/{v1}/...`\
  Example: `/api/v2/liquidity/...`
* **Documentation/SDK (non-routing):** `info.version` uses SemVer (e.g., `2.0.1`) to signal doc/SDK updates within the same major.

**Pin to `/v1`** in your base URL to avoid surprises. We only bump the **path major** when introducing **breaking changes**.

***

## Compatibility Guarantees (Non-breaking)

Within the same **major** (e.g., `v1`), we may ship changes that are **backward-compatible**. Your integration should continue to work if you:

* Ignore **unknown fields** in responses.
* Don’t assume enums are closed sets (handle **new enum values** gracefully).

Examples of non-breaking changes:

* Adding **new endpoints** or **resources**
* Adding **optional** request parameters
* Making a **required** parameter **optional**
* Adding **new properties** to response objects
* Changing the **order** of properties in JSON
* Adding **new enum members** (if clients treat unknown values safely)

***

## What Counts as a Breaking Change

Changes that can require code updates or alter behavior in a way that can break existing clients. These will trigger a **new major path** (e.g., `/v3`):

* Removing an endpoint, field, or enum value
* Renaming fields or changing field **types**
* Changing required parameters or **tightening validation** (e.g., narrower ranges, new mandatory header)
* Altering response structure (e.g., changing pagination shape)
* Changing default business logic in a way that affects results (e.g., default sort/filters, monetary rounding)
* Changing error envelope format

***

## Deprecation & Sunset Policy

When we plan to remove or alter behavior in a way that breaks compatibility:

* We **announce** in the changelog and docs.
* We add **deprecation headers** on affected endpoints where possible:
  * `Deprecation: true`
  * `Sunset: <RFC 1123 date>` (planned removal date)
  * `Link: <https://docs.mansa.io/changelog#deprecations>; rel="deprecation"`
* We provide **at least 90 days' notice** before removal (unless a security or compliance issue requires faster action).

***

## Version Pinning

Always target a **specific major**:

```http theme={null}
GET https://api.mansa.xyz/api/v2/liquidity/management/loans?limit=50&page=1
authorization: Bearer <token>
x-api-key: <key>
```

Do **not** rely on unversioned paths. Minor and patch updates within `v1` won’t change routing or the error envelope.

***

## Forward-Compatibility Tips

To minimize friction when we add features within a major:

* **Ignore unknown fields** in JSON objects.
* Treat enums as **open**; handle **unexpected values** by mapping to a safe fallback.
* Validate inputs using the spec, but prefer **soft validation** where safe (to tolerate new optional params).
* Use **structured errors** (`error.type`, `error.code`, `param`) rather than string-matching messages.

***

## Upgrading to a New Major

When a new major path (e.g., `/v3`) is released:

1. Review the **Upgrade Guide** in the changelog.
2. Test critical flows against `/v3` in **sandbox**.
3. Roll out gradually; log and monitor **error codes** and **rate limits**.
4. Switch production traffic once parity is confirmed.

***

## Current Version Status

| Version | Status     | Notes                                               |
| ------- | ---------- | --------------------------------------------------- |
| v2      | **Active** | Current version. Recommended for all integrations.  |
| v1      | **Sunset** | No longer available. All v1 endpoints return `404`. |

***

## Frequently Asked Questions

**Q: Will you add fields to responses without a new version?**\
A: Yes—adding fields is **non-breaking**. Clients should ignore fields they don’t use.

**Q: Will enum values change?**\
A: We may **add** enum values in the same major. We **won’t remove or rename** existing ones without a new major.

**Q: How are errors versioned?**\
A: The **error envelope** shape is stable within a major (`{ "error": { "type", "code", "message", ... } }`). New `error.code` values may appear.