Skip to main content
Iron versions the API by date. Send X-API-Version to pin the response shapes your integration was built against. Routes never change, so a version switch is a header change.

​
Header: X-API-Version

Send the version as an ISO date (YYYY-MM-DD):
Every endpoint under /api reads this header. Omit it and you get the default version.

​
Supported Versions

GET /spec/versions returns the live list, the default, and the location of each version’s OpenAPI spec.

​
The Default Version

A request with no X-API-Version header, or an empty one, is served 2025-03-13. Defaulting to the newest version instead would hand you response shapes your client has never parsed, which is the break versioning exists to prevent. Send the header explicitly. It costs one line and it pins your integration to shapes you have tested.
Moving the default to a newer version is itself a breaking change for callers that send no header, so it is announced in advance with a migration window rather than changed underneath you.

​
Exploring a Version

The API Reference tab has a version selector. Switching versions regenerates every endpoint page from that version’s spec, so what you see is what that version returns. The FedNow deposit rail, for example, appears on autoramp responses under 2026-07-01 and is absent under 2025-03-13. The selector tags each version so the two defaults are never confused: Latest is what the selector opens to, and API default (no header) is what an unversioned caller actually gets. They will not always be the same version.
A version makes a shape available. Some shapes also depend on your account configuration, so a rail your account is not enabled for stays absent even on a version that defines it.

​
Downloading a Spec

Each version is published as its own OpenAPI document, served straight from the API and always current. Every document below is available from both environments, and none of them needs an API key. Take the base URL for the environment you are integrating against:
  • Sandbox: https://api.sandbox.iron.xyz
  • Production: https://api.iron.xyz
So the 2026-07-01 document is at https://api.sandbox.iron.xyz/spec/2026-07-01 in sandbox and https://api.iron.xyz/spec/2026-07-01 in production. Pick the environment deliberately: the two documents declare different servers URLs, and the sandbox one additionally carries the /sandbox/* simulation endpoints, which do not exist in production. Reference pages also offer Download API spec in the page context menu, which gives you the spec for the version you are viewing. If you generate a client, generate it from a dated spec and send that same date as X-API-Version. Moving versions then becomes one action: regenerate, and the date your client sends moves with it.

​
Errors

An unknown or malformed version returns 400 Bad Request. Iron never falls back to a nearby version, because silently serving different shapes than you asked for is the failure versioning is meant to remove.
Only the canonical spelling is accepted. 2026-7-1 is rejected as version_malformed, because caches key on the raw header value and equivalent spellings would fragment them.

​
What Mints a New Version

A new version is cut for changes that break a client which parses responses strictly:
  • A response field is removed or renamed
  • A variant is added to an existing enum or union
  • A request body changes shape
Additions that break nobody do not mint a version and land on every version: a new optional response field, a new endpoint, a new value in a field documented as open-ended.

​
Key Considerations

  • Echo: every /api response carries X-API-Version with the version actually served, including the default. Read it to confirm which version you are on without inspecting shapes.
  • Caching: responses carry Vary: X-API-Version, so shared caches key on the version.
  • Idempotent retries: a retried POST with the same IDEMPOTENCY-KEY returns the stored body and status without response headers, so it carries no version echo. See Idempotency.
  • Unversioned surfaces: token and market data endpoints have no version-gated shapes and ignore the header.