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" \
  -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.

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

  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.

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 →