Skip to main content

Versioning & Deprecation

How Colter versions hosted APIs, CLI behavior, MCP tools, and Evidence Pack schemas.

TL;DR: Treat Colter JSON as forward-compatible. Breaking changes get a new API prefix, a new MCP tool name, or a new Evidence Pack schema version.

Hosted API (/api/v1/*)

  • Hosted endpoints are versioned by URL prefix.
  • Breaking changes ship under a new prefix such as /api/v2.
  • Additive fields may appear in the current version.

CLI

  • CLI releases use semver tags such as vX.Y.Z.
  • If you parse --json output, ignore unknown fields instead of hard-failing.

MCP Tools

  • MCP tool names are stable.
  • Additive input or output fields may appear without a rename.
  • Breaking changes should use a new tool name or ship with a migration note.
  • Tool schema snapshots are published at /mcp-tools.schema.json.

Evidence Packs

  • Every pack declares a schema version in manifest.json.
  • Additive changes stay within the current schema version.
  • Breaking changes increment the schema version and require a migration path.