# Versioning and changes

> How the API changes, what counts as a breaking change, and how you're warned months before anything stops working.

The version is in the path: `/v1`. Within `v1`, the API only grows. The [OpenAPI document](#the-openapi-document) is the promise, and our build refuses any change to the code that would break it.

## Changes that can happen any time

- A new call.
- A new optional field or query parameter.
- A new field in an answer.
- A new value in an answer's list of choices, like a new pipeline stage or error code.
- A new webhook event.
- Accepting input that used to be refused.

Build clients that ignore fields and values they don't know, and branch on `error.code`, never on the wording of `message`.

## Breaking changes

These count as breaking:

- removing or renaming a call, a method or a field in an answer;
- an answer field that can now be `null` or another type, or isn't always there;
- a success status a call no longer answers with;
- a request field or parameter that becomes required, is no longer read, or accepts less than it did (a lower maximum, a shorter length, a new format);
- a field's format changing, like a date-time becoming a date;
- a webhook event removed, or its payload changing incompatibly;
- a call needing a different scope;
- an existing field or value coming to mean something else.

A breaking change ships only after the thing it removes has been **deprecated for at least 180 days**, or in a new version (`/v2`) with `v1` kept running alongside it for at least as long. Each one comes with a note that says what to use instead.

## How you're warned

Every answer from a deprecated call carries:

- `Deprecation: @<unix time>` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)), when it was deprecated;
- `Sunset: <HTTP date>` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), when it stops answering;
- `Link: <…>; rel="deprecation"` (and `rel="sunset"`), pointing to the note that says what to use instead.

The OpenAPI document marks deprecated calls and fields too. Watch for the `Deprecation` header in your logs: it arrives months before anything stops working.

## The OpenAPI document

`GET /openapi.json` needs no credential and describes the whole API as OpenAPI 3.1: every call, its inputs, every answer's fields, the scope it needs and its errors. Load it into Postman, Insomnia or a client generator.

```bash
curl https://workspace.brokerandagent.com/api/public/v1/openapi.json
```

## Related

- [Requests, errors and limits](https://brokerandagent.com/developers/api/requests)
- [The API reference](https://brokerandagent.com/developers/api/reference/contacts)

---

Source: https://brokerandagent.com/developers/api/versioning
