# Versions and changes

The API is `/v1`. Inside `/v1` we only add.

## What we never do in /v1

- Remove or rename an endpoint, a parameter or a field.
- Add a required parameter.
- Change a field's type.
- Remove a value from a list of values.
- Accept less than we did: a limit only ever rises.
- Move an endpoint between plans.

## What we may add

- New endpoints, optional parameters, fields and headers.
- New values in a list of values: `kind`, `code`, sectors.

Ignore fields and values you don't know, and your program keeps working.

Ids and cursors are opaque strings. Their length may change.

## When something is retired

We announce it in the [changelog](/docs/changelog) and give at least 12 months.

From the announcement, its answers carry:

```
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://bullpen.news/docs/changelog#v12>; rel="deprecation"
```

When you see `Deprecation`, log a warning with its `Link` and move before the `Sunset` date. After it, the endpoint answers `410 Gone`. If we see your account using something we're retiring, we email you when it's announced and again 30 days before it goes.

## Keeping track

- The [changelog](/docs/changelog), and its [RSS feed](/docs/changelog.xml).
- [openapi.json](https://api.bullpen.news/openapi.json): its `info.version` goes up with every change.