Skip to main content

​
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

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:
    Sunset is in the CORS expose-headers list — browser clients can read it.
  2. 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

Every webhook envelope carries apiVersion (date-based). Receivers can lock to a specific schema even as new versions roll out: Receivers can inspect apiVersion and branch payload handling on it. See Webhook endpoints for the locked envelope shape.

​
Surfaces an agent should know

​
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.