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
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. |
/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:
-
The
Sunset HTTP response header carries an RFC 8594 date for the planned removal:
Sunset: Wed, 30 Nov 2027 00:00:00 GMT
Sunset is in the CORS expose-headers list — browser clients can read it.
-
The changelog entry under the Releases tab 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
Webhook payloads pin to a date-based apiVersion so subscribers can lock to a specific schema even as new versions roll out:
| Webhook surface | Current apiVersion | Where it appears |
|---|
| Page webhooks (orders) | 2026-05-08 | apiVersion field on every event payload |
| Agent webhooks (user events) | (no payload version field today) | n/a — schema additions are additive |
apiVersion and write payload-handling code that branches on it. See Page webhooks for the locked schema.
Surfaces an agent should know
| You depend on | How to verify |
|---|
The error.type enum | 10 locked values. See 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. |
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.