---
title: "What /v1 promises"
description: "What /v1 promises, and what has changed."
canonical: "https://writavo.com/docs/versioning"
last-updated: "2026-09-30"
---

# 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:

- endpoints, optional request fields and response fields,
- values to a read-only enum (a new `article.status`, a new webhook event).

We will not:

- remove a field, or 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 ships as `/v2`, at a different base URL, with `/v1` supported alongside it. The promise binds from general availability; the one earlier exception is 1.5.0 below.

## What your client must tolerate

- **Ignore response fields you do not recognise.** A strict parser breaks on the first new field.
- **Treat every read-only enum as open.** `article.status`, `webhook.event` and `error.code` can gain values; handle an unknown one gracefully.
- **Handle an unknown error code by 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. A deprecation would be announced here with a date and keep working for the lifetime of `/v1`: a recommendation to move, never a removal.

## Changelog

The specification is versioned with the API at [/openapi.yaml](/openapi.yaml). Current version: `1.8.0`.