Versioning & deprecation

The public API is versioned in its path: every endpoint lives under /api/v1/. That version is a promise about compatibility, and this page is what the promise actually says.

What v1 guarantees#

While v1 is the current version, we will not:

• remove an endpoint, or change its HTTP method or path
• remove a field from a response, or change the type of an existing field
• add a new required request parameter
• change the meaning of an existing field without renaming it
• tighten validation so that a request which succeeded yesterday fails today

What is not a breaking change#

These can land at any time, so your client must tolerate them:

• New fields in a response. Parse permissively and ignore what you do not recognise. This is the single most common way an integration breaks on a change that was not breaking.
• New optional request parameters.
• New endpoints, and new enum values in a field documented as extensible.
• New MCP tools, or new optional arguments on an existing tool.
• Ordering of items in a response, unless the endpoint documents a sort.
• Error message wording. Branch on the code field, never on the prose in error. The prose is written for humans and gets improved.

Deprecation#

When something has to go, it goes in stages:

1. Announced. The changelog records it, with the replacement and the date. The changelog has an RSS feed.
2. Marked. Affected responses carry a Deprecation header and, where a date is set, a Sunset header (RFC 8594). MCP tool responses carry the same notice inline so an agent sees it.
3. Removed. No sooner than 90 days after the announcement, and never inside v1. A removal means a new version.

If a change is forced on us by a security issue or an upstream provider, we may have to move faster. In that case we will say so explicitly and contact affected accounts directly rather than relying on you reading a changelog.

Version 2#

There is no v2. If one is introduced, v1 will keep serving for at least 12 months after v2 becomes generally available, and the migration will be documented endpoint by endpoint rather than as a single "rewrite your client" note.

MCP#

The hosted MCP server is versioned separately from the REST API, because MCP clients negotiate capabilities rather than pinning a URL. The same rules apply in spirit: tools are not removed or given new required arguments without the notice period above, and the live tool catalog is published at /api/v1/mcp/tools.json so you can diff it yourself.

Staying informed#

• Changelog and its feed
• The OpenAPI 3.1 contract, which is generated from the live routes
• security@texttoquant.com for anything urgent