What /v1 promises

Within /v1 we may:

• add a new endpoint,
• add a new optional request field,
• add a new response field,
• add a new value to a read-only enum, for example a new article.status if the pipeline grows a stage, or a new webhook event.

We will not, within this version:

• remove a field,
• remove or narrow an enum value,
• rename anything,
• make an optional request field required,
• change the HTTP status code of an existing outcome.

The promise above only holds up if clients are written to accept the additions it allows. Two rules:

• Ignore response fields you do not recognise. A strict parser that rejects unknown keys will break the first time we add one, and adding one is explicitly permitted.
• Treat every read-only enum as open. article.status, webhook.event and error.code can all gain values. Fall through gracefully on a value you do not know rather than throwing.

An unknown error code should be handled as a generic failure of its HTTP status class. A 402 you have never seen is still a payment problem.

Nothing in /v1 is deprecated today. If that changes, it will be announced here with a date, and the behaviour will keep working for the lifetime of this version. A deprecation is a recommendation to move, never a removal.

The specification itself is versioned with the API and served at /openapi.yaml. It currently reads 1.0.0.