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/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.
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
Reference datasets (ADR, HS, Incoterms, UN/LOCODE, airlines) are versioned against their upstream source edition. The current edition is shown on each tool's page and in the /api/health response under data_versions. 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.