Versioning

What we may do inside /v1

• Add a new endpoint, a new tool, or a new optional request field.
• Add a new field to a response. Parse responses permissively.
• Add a new value to an open vocabulary (a new outcome, a new merchant_status step). Handle unknown values gracefully.
• Reword a message. The code beside it stays.

What we will not do inside /v1

• Remove or rename a field, an error code, or a tool.
• Change the type or meaning of an existing field.
• Make an optional request field required.
• Change what an outcome means. confirmed will always mean the business confirmed, with evidence.

If we ever need to break something

It ships as /v2 alongside /v1. Deprecation is announced by email to every developer with a key used in the previous 90 days, and the old version keeps running for at least six months after that notice. Nothing is switched off because it looked unused.