FreightUtils ships three things developers version against: a public REST API, an MCP server for agent use, and a tool contract — the input/output shape of each individual tool. This page explains how each is versioned and what stability means in practice.
REST API stability contract
The REST API at www.freightutils.com/api/* is the primary integration surface. It's unversioned in the URL (no /v1/) because all changes follow the stability contract below — a change that would break clients doesn't ship without notice.
What counts as a breaking change
- Removing or renaming a response field
- Changing a field's type (string → number, etc.)
- Removing or renaming a query/path parameter
- Changing a default that alters response shape
- Retiring an endpoint URL
What counts as additive (anytime)
- Adding a new endpoint
- Adding a new optional query parameter
- Adding a new field to a response
- Widening an enum (adding new accepted values)
- Bug fixes that restore documented behaviour
Breaking-change notice
Breaking REST changes get at minimum 3 months notice via: (a) a changelog entry tagged API Change, (b) a deprecation entry, (c) Deprecation and Sunset response headers on affected endpoints, and (d) an email to holders of affected API keys.
MCP server — semantic versioning
The MCP server ships as freightutils-mcp on npm and follows semantic versioning:
- Major (x.0.0) — a breaking change to tool names, tool input schemas, or server transport. Rare.
- Minor (1.x.0) — a new tool added, or a new optional argument on an existing tool. Safe upgrades.
- Patch (1.0.x) — bug fix, data refresh, or output accuracy improvement. Always safe to upgrade.
The hosted Streamable-HTTP endpoint at www.freightutils.com/api/mcp mirrors the latest minor of the npm package within 24 hours of release. If you need a pinned version, use the npm package via npx freightutils-mcp directly. The legacy URL /api/mcp/mcp remains live for existing clients.
Tool contract stability
Each tool — whether called via REST, MCP, or the npm package — has its own contract: a stable set of inputs and a stable shape of outputs. Tools reach stability in stages.
Stability tiers
- Stable — the tool is in general availability. Its inputs, outputs, and semantics follow the contract above. This is the default.
- Preview — shape is likely to change based on feedback; use at your own risk. Marked with
"stability": "preview"on the tool's API docs entry and in the MCP tool description. - Deprecated — still functional but scheduled for removal; see deprecation policy.
Subscribing to breaking-change notifications
Three channels, in order of recommended coverage:
- Changelog RSS — subscribe to /changelog.xml. Every API Change and Deprecation entry lands here first. This is the most reliable channel.
- Email to API key holders — if you've registered an API key, you'll receive an email for any breaking change to an endpoint your key has hit in the last 90 days. Register at /api-docs.
- Roadmap page — see /roadmap for what's planned. In-progress items often ship behind a preview flag before becoming stable.
Data versioning
Editioned reference datasets are versioned against their upstream source edition. Today the editions registry tracks 7 of them (adr, emissions, hs, ics2, incoterms, unlocode, validate); continuous datasets such as airlines and airports carry per-record verification dates instead of an edition. The edition served, the authority's current in-force edition and the date that was last checked are returned by the /api/health response under data_versions, and every response envelope carries the same three fields per dataset. Dataset refreshes are additive unless the upstream body itself removes entries (rare, signalled the same way as an API breaking change).
Questions
Contract unclear, spec ambiguous, or a change surprised you? Email contact@freightutils.com — that's always faster than guessing.