Versioning and change policy

The version is in the path. Every endpoint lives under /api/v1/public, v1 is the only version, and a URL that worked will keep meaning the same thing for as long as v1 is current. A second version, if it ever exists, will be a second path rather than a change of behaviour under the first.

What we can change without warning

These are additive: existing calls keep working, existing fields keep their meaning, and a client that ignores what it does not recognise is unaffected. Write your integration so that they are, and most of our changes stop being your problem.

• Adding a new field to a response. Parse permissively — an unknown field is not an error.
• Adding a new optional parameter, with the existing default unchanged.
• Adding a new endpoint, or a new value to a set we already describe as open-ended.
• Adding a new error code for a condition that previously fell under a broader one. Branch on the codes you handle and treat the rest as their status class.
• Making validation more permissive — accepting an input we used to reject.

What counts as breaking

These change the meaning of a call that already works, so they cannot land quietly on a version that is current.

• Removing or renaming a response field, or changing its type — including making a field that was always present nullable.
• Removing an endpoint, or changing the status code a condition answers with.
• Adding a required parameter, or tightening validation so a previously accepted input now fails.
• Changing what a credit buys: charging for a call that was free, or charging more for the same result.
• Changing the meaning of a field while keeping its name — the worst kind, because nothing on your side errors.

How you find out

Four channels, and they are generated from the same source rather than maintained by hand, so a change cannot reach one and miss another.

• The changelog records every contract, price and sourcing change on the day it happens.
• The Atom feed at /changelog.xml carries the same entries — subscribe rather than remembering to check, because nobody polls a documentation page.
• Every endpoint page shows its current availability, and every reference page is generated from the same typed contract the API is described by.
• The OpenAPI document stamps x-availability on each operation, so a build step can assert on it without reading a page.

Deprecation, when it happens

A deprecated endpoint keeps working. Its page says it is deprecated and what replaces it, the changelog entry says the same, and the OpenAPI document stops listing it once it is no longer something new integrations should build on. Nothing disappears from under a running integration without that sequence happening first, in public.