# Versioning

Source: https://modulify.ai/docs/api/versioning

What the v1 in every address promises, what can change without notice, and how to write code that keeps working.

Every address starts with `/v1`. That number is a promise about what stays the same, so code written today keeps working as Modulify grows.

## What v1 keeps

Within v1:

- **Methods are not removed or renamed.** A method name that works today keeps working.
- **Arguments are not removed, renamed or retyped.** An argument that takes a string today takes a string tomorrow.
- **Required arguments stay the same.** A method never starts requiring an argument it did not require before.
- **The envelope stays the same.** Every answer keeps `success`, `message`, `data`, `code` and `version`, plus `count` on lists.
- **Status codes keep their meaning.** A `401` is always the token, a `429` always means slow down.

Anything that would break one of these comes as a new version beside v1, not as a change to it.

## What can change at any time

These are additions, so they arrive without a new version:

- **New methods.** The catalog grows as Modulify does. `GET /v1/tools` and the [OpenAPI description](https://modulify.ai/docs/api/openapi) always list the current set.
- **New optional arguments.** Leaving them out keeps the old behaviour.
- **New fields in `data`.** An answer can carry more than it did.
- **New values in a list of choices** that an answer reports, such as a new publish step or a new event type in `get_job`.
- **Wording.** `message` is written for people. Do not match on its exact text. Branch on `code`, and on fields such as `data.reason` where a method provides them.
- **Limits.** Numbers such as the per-minute budget and queue sizes can be raised or lowered by Modulify. Read them from the `X-RateLimit` headers and from the answers rather than hard-coding them.

## Write code that lasts

- Ignore fields you do not recognise rather than failing on them.
- Treat an unknown value in a list of choices as "something else" rather than an error.
- Branch on status codes and named fields, never on message text.
- Read limits at run time.

## How changes are announced

New methods, new arguments and anything else a developer should know about appear in the [changelog](https://modulify.ai/docs/changelog). Each method's page always describes its current behaviour.

## Next

- [All methods](https://modulify.ai/docs/api/methods) for the current catalog.
- [OpenAPI](https://modulify.ai/docs/api/openapi) to generate a client.