Versioning

How the API names its versions, what can change without one, and how much notice you get before anything you rely on stops working.

The Layout-Version header

Versions are dates. The current version is 2026-10-01, and it is the only one. Send Layout-Version on a request to pin the version you code against. Leave it out and you get the current version. Every answer from an endpoint, errors included, says which version answered in its own Layout-Version header.

curl https://api.layout.link/v1/whoami \
  -H "Authorization: Bearer $LAYOUT_SECRET_KEY" \
  -H "Layout-Version: 2026-10-01"

A version this API does not answer is 400 unsupported_version, and the message lists the versions it does. Nothing runs.

Pin a version in production. Then a new version changes nothing for you until you change the header yourself, after reading what it changes.

Changes without a new version

Additive changes ship into the current version, so write code that tolerates them:

  • A new endpoint, or a new optional request field or query parameter.
  • A new field in a response or a webhook payload. Ignore fields you do not know.
  • A new error code. Handle one you do not know by its HTTP status.
  • A new event type. You receive it only once a subscription lists it.
  • A new Limit name, or a raised limit.
  • Message text. message is for a person; switch on code.

How a breaking change ships

A breaking change is anything that can stop working code from working: removing or renaming an endpoint, a field or an error code, changing a field's type or meaning, making an optional field required, or changing what a status code means.

That is the policy going forward. 2026-10-01 is the only version, and no route answers differently by version yet. Breaking changes announced in the changelog since 2026-10-01 shipped into it, so pinning it does not hold them back. Read the changelog entry for each one.

  1. It ships as a new dated version. The version you pinned keeps answering exactly as it did.
  2. It is announced in the changelog on the day it ships, marked breaking, naming the new version, what changed and what to do about it.
  3. The old version keeps working for at least 180 days from that announcement. A version is never removed without a changelog entry that gives the date it stops answering.
  4. After that date a request that pins it is 400 unsupported_version. A request without the header gets the current version.

Deprecation

A deprecated field stays in every version Layout answers today, marked deprecated in the OpenAPI specification, and its answers carry a Deprecation header and a Link header with rel="deprecation" pointing at the changelog entry. It is removed only in a new dated version, with at least 180 days’ notice.

Today User.handoffUrl, in the POST /v1/users answer, is deprecated. That answer carries Deprecation: @1792540800 and a link to the changelog entry, including when an Idempotency-Key replays it. The refunded order state is deprecated too and is never sent; read refunded_minor instead.

What is not versioned

  • The MCP server. Layout-Version applies to the REST API. MCP tools are described to the model on every connection, and a change to one is in the changelog.
  • Limits. A change to a limit is in the changelog.
  • The console. It is a product, not an interface your code calls.
Next
Changelog →