Versioning and changes

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

Updated Nov 11, 2026

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 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), when it was deprecated;
  • Sunset: <HTTP date> (RFC 8594), 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.

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

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.