Versioning

Additive only under /v1. What that promise covers and what a breaking change would look like.

The promise

From the first external key, the shape of /v1 only grows. A field is never removed or renamed, a type never narrows, an enum never loses a value. A removal or a rename is /v2.

What can change without notice

• A new field on any object. Ignore fields you do not know.
• A new value in an open enum. relations[].kind says so in the spec: synonym and antonym today, more kinds can follow.
• A new error code. Fall back to generic copy by status.
• A new operation or a new optional parameter.
• The data itself. Entries are refreshed, examples rewritten, ranks recomputed. updated_at moves.

What cannot

• A required field going away or becoming nullable.
• A parameter changing meaning.
• A path changing.

Deprecation

When /v2 exists, /v1 keeps answering for twelve months from the announcement, which goes out in the changelog and by email to every account with a live key.

The contract

The v1 OpenAPI spec is the contract. Every example on these pages is checked against the spec's schema when the site is built, so what you read here is what the server does.