Versions and changes

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 and give at least 12 months.

From the announcement, its answers carry:

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.

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

Keeping track

• The changelog, and its RSS feed.
• openapi.json: its info.version goes up with every change.