Versioning and changes
How the API changes, what counts as a breaking change, and how you're warned months before
The version is in the path: /v1. Within v1, the API only grows. The OpenAPI document is the promise, and our build refuses any change to the code that
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
nullor another type, orisn’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
How you’re warned#
Every answer from a
Deprecation: @<unix time>(RFC 9745), whenit was deprecated; Sunset: <HTTP date>(RFC 8594), whenit stops answering; Link: <…>; rel="deprecation"(andrel="sunset"), pointing to the note that says whatto use instead.
The OpenAPI document marks deprecated calls and fields too. Watch for the Deprecation header in your logs: it arrives months before
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
curl https://workspace.brokerandagent.com/api/public/v1/openapi.jsonRelated#
Something missing or wrong? Email support@brokerandagent.com and