# What /v1 promises

Additive only. Anything that could break a working integration ships as a new version, with this one supported alongside it.

## The promise

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.

> Any of those would ship as `/v2`, at a different base URL, with `/v1` supported alongside it.

## What your client must tolerate

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.

## If something is ever deprecated

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.

## Changelog

The specification itself is versioned with the API and served at [/openapi.yaml](/openapi.yaml). It currently reads `1.0.0`.