Versioning & stability

Two things are versioned independently:

• The URL path (/v1/) versions the API contract — request/response shapes. Breaking shape changes will ship under a new path version.
• versions.taxonomy and versions.patterns version the classification behaviour. A patterns bump means the same title may classify differently than before; re-run any cached classifications if you depend on consistency.

Forward compatibility

Classification values may be added without an API version bump. Treat string values and multi-value fields as open-ended rather than hard-coding a public taxonomy.

Caching classifications

Results are deterministic per pattern version, so they are safe to cache. Pin the versions object returned with every response alongside your cached results, and invalidate when either version string changes.