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

# Versioning

> How Marea versions its API: stable URL prefix, additive evolution, the Sunset header, and webhook payload pinning.

# Versioning

Marea's public API is on **v1**. This page documents what counts as a breaking change, how the API evolves additively, and where versions surface to clients (URL, headers, webhook payloads).

## URL versioning

| Surface                       | Current value                                   | Stability                                                   |
| ----------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| URL prefix                    | `/v1/*`                                         | Stable. Will remain mounted at least 12 months after v2 GA. |
| OpenAPI spec URL              | `https://api.mareaalcalina.com/v1/openapi.json` | Stable. Mintlify pulls this for the API reference tab.      |
| Public hosted-storefront base | `https://marea.pro/`                            | Stable.                                                     |

A breaking change ships under a new prefix (`/v2/*`). v1 remains live during the deprecation window. There is no `Marea-Api-Version` header today — version is in the URL.

## What counts as additive (non-breaking)

The following changes can land on `/v1/*` without notice:

* Adding new endpoints.
* Adding new fields to a response body.
* Adding new optional fields to a request body.
* Adding new values to an open-ended enum (only if the field is documented as open-ended).
* Adding new `error.code` values within an existing `error.type`.
* Adding new headers (request or response).
* Tightening internal implementation (cache TTLs, retry backoff, etc.) when the external behavior is unchanged.

Clients should be **forward-compatible** with all of the above. In particular:

* Treat unknown fields in responses as ignorable.
* Branch on `error.type` first (closed 10-value enum); fall back to `error.code` when finer-grained.
* Do not parse `error.message` — it is localized via `Accept-Language` and may change.

## What counts as breaking

The following changes never ship to `/v1/*`; they require a new prefix:

* Removing or renaming a field, header, or endpoint.
* Changing a field's type (e.g. string → number).
* Tightening a response (e.g. an optional field becoming required, a nullable field becoming non-null).
* Changing the meaning of an enum value (or removing one).
* Changing the 10-value `error.type` enum.
* Changing the `Idempotency-Key` contract (header name, length, character class, snapshot cap).

## Deprecation signaling

When a v1 endpoint or field is scheduled for sunset, two signals surface:

1. The **`Sunset` HTTP response header** carries an RFC 8594 date for the planned removal:

   ```http theme={null}
   Sunset: Wed, 30 Nov 2027 00:00:00 GMT
   ```

   `Sunset` is in the CORS expose-headers list — browser clients can read it.

2. The **changelog** entry under the [Releases tab](/changelog) documents the rationale and the migration path.

Clients should monitor `Sunset` headers in production and surface them to operators. There is no `Deprecation` header in v1 today; rely on `Sunset` + the changelog.

## Webhook payload versioning

Every webhook envelope carries `apiVersion` (date-based). Receivers can lock to a specific schema even as new versions roll out:

| Webhook event family   | Current `apiVersion` | Where it appears                     |
| ---------------------- | -------------------- | ------------------------------------ |
| `user.*` and `order.*` | `2026-05-12`         | `apiVersion` field on every envelope |

Receivers can inspect `apiVersion` and branch payload handling on it. See [Webhook endpoints](/concepts/webhooks) for the locked envelope shape.

## Surfaces an agent should know

| You depend on                 | How to verify                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------------ |
| The `error.type` enum         | 10 locked values. See [Errors](/concepts/errors). Branch on this, not `code` or `message`.             |
| The scope set                 | Defined in `src/api/services/scope.constants.ts`. New scopes are additive; existing scopes are stable. |
| The `Idempotency-Key` shape   | 1–255 ASCII printable. Locked. See [Safe mutations](/concepts/safe-mutations).                         |
| The `stf_` / `prd_` id format | Locked. Internal ids never appear on the wire.                                                         |

## Verification in code

* `src/api/server.ts` — `/v1/*` mount point.
* `src/api/middleware/cors.ts` — `Sunset` in the expose-headers list.
* `src/api/types/webhook.types.ts` — `PAGE_WEBHOOK_API_VERSION` constant.
* `src/api/contracts/error.zod.ts` — the locked 10-value `type` enum.