API Versioning

Why versions exist

The /v1 path never changes, but some behaviour has to move over time. The most visible case is the default Standards Release a conversion follows when you do not name one. An API version is a date, YYYY-MM-DD, that freezes that behaviour: pin a date and your requests behave the same way until you choose to move.

You never have to send a version. Without one, you get the current version.

The version dates

The list is closed. Only the dates below are accepted:

A released date is never removed or re-pointed: pinning a date is a promise that its behaviour stays put. A behaviour change, such as moving the default release, ships as a new date, and the current version moves to it. Every such move is announced in the changelog first.

Planned: the 14 November 2026 release is due to add 2026-11-14, with default release SR2026, and make it the current version. It is not accepted yet; sending it today is a 400. 2026-06-01 keeps SR2025 after the move. See Standards Releases.

Send a version

Send the X-Api-Version request header on any /v1 route that takes an API key (convert, normalize, validate, batch, formats and the rest):

curl -sS -X POST "https://api.transmute.403fin.io/v1/convert?to=camt.053" \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "X-Api-Version: 2026-06-01" \
  -H "Content-Type: text/plain" \
  --data-binary @statement.mt940

Every response on those routes echoes the version the request was served under in the X-Api-Version response header, including errors such as 401 and 429:

HTTP/1.1 200 OK
X-Api-Version: 2026-06-01

An unknown date is a invalid-input 400 that lists the supported dates. It is checked before authentication:

{
  "type": "https://docs.transmute.403fin.io/errors/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "unsupported X-Api-Version "2027-01-01": supported versions are 2026-06-01",
  "instance": "/v1/formats"
}

POST /v1/oauth/token does not read the header.

Pin a version on an API key

An API key can carry a version pin. It applies to every request made with that key that sends no X-Api-Version header. This suits an integration you cannot easily redeploy.

• The pin is set when the key is created (the portal's create-key request takes an optional api_version, from the same closed list; anything else is a 422).
• It cannot be changed afterwards. To move, mint a new key and revoke the old one. Rotating a key copies the pin to the new key.
• A header on the request still wins over the key's pin.
• OAuth access tokens carry no pin: they follow the header, or the current version.

Resolution order

For the API version:

1. the X-Api-Version request header, if sent;
2. otherwise the calling API key's pin, if it has one;
3. otherwise the current version.

For the Standards Release a request is converted, normalized or validated under, the first rule that applies wins:

1. an explicit srVersion: envelope options.srVersion, then ?srVersion=, then the X-Transmute-SR-Version header;
2. the default release of the resolved API version (the table above);
3. the service default, SR2025.

So an explicit srVersion always wins over any version date:

curl -sS -X POST "https://api.transmute.403fin.io/v1/convert?to=pacs.008&srVersion=SR2026" \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "X-Api-Version: 2026-06-01" \
  -H "Content-Type: text/plain" \
  --data-binary @mt103.txt
# runs under SR2026, although 2026-06-01 defaults to SR2025

Batch items follow the same order per item. An item with no srVersion is stored with the release its request resolved to, so a job accepted under one version is processed under it even if the current version moves while the job waits.

What each version changes

Choosing a strategy

The SDKs take the version once as a client option and send nothing when you leave it unset: apiVersion in TypeScript, api_version in Python, WithAPIVersion in Go, .apiVersion(...) in Java and CreateHttpClient(apiVersion: ...) in .NET.