API Versioning

The Mural API has dated versions. A version is a date, for example 2026-11-01. The current version is 2026-11-01.

How Mural picks the version

Each request uses one version. Mural picks it in this order:

1. The Mural-Version request header, if you send it.
2. The version pinned to your organization.

You do not need to send the header. Your integration keeps working with no code change.

Your organization's pinned version

Each organization that uses the API has a pinned version:

• An organization that had an API key on 2026-11-01 is pinned to 2026-11-01.
• A new organization is pinned to the current version when it creates its first API key.

A request made on behalf of a child organization (with the on-behalf-of header) uses the version pinned to the parent organization.

Your sandbox organization and your production organization each have their own pinned version.

Send a version on a request

To ask for a version on one request, send the Mural-Version header:

GET /api/accounts HTTP/1.1
Host: api.muralpay.com
Authorization: Bearer <your API key>
Mural-Version: 2026-11-01

The header applies to that request only. It does not change your pinned version.

Read the version that Mural used

The Mural-Version response header shows the version that Mural used. It is on every response where Mural knows the version: when you send a supported Mural-Version header, or after Mural accepts your API key. A 403 or 429 response carries it too:

HTTP/1.1 200 OK
Mural-Version: 2026-11-01

It is not on these responses:

• A 400 for an empty or unknown Mural-Version header.
• A request with no Mural-Version header that fails before Mural accepts your API key and your on-behalf-of header, for example a 401 for a bad API key. Mural does not know your organization yet, so it does not know your pinned version.

Browser clients can read this header: it is in Access-Control-Expose-Headers.

An empty or unknown version

A request with an empty Mural-Version header, or with a version that Mural does not support, returns 400 with an UnsupportedApiVersionError body. The error lists the supported versions:

{
  "errorInstanceId": "a3b033fc-0000-0000-0000-000000000000",
  "name": "UnsupportedApiVersionError",
  "message": "The Mural-Version header is empty or names an unsupported API version.",
  "params": {
    "supportedVersions": ["2026-11-01"]
  }
}

A request with a bad Mural-Version header gets this error whatever API key it sends.

To fix it, send one of params.supportedVersions, or remove the header to use your pinned version.