API changelog

Entries

1. The public API is available, at /api/v1

   Added · 27 October 2026

   The public API answers at https://api.barrierops.com/api/v1. Every page in this section now documents it as it runs: every command and program on them was run against it, and is printed with what came back.

   What it has: the assets, scans, issues, documents, vendor products, evidence ledger and reports of the organisations a key reaches, the evidence check, and a lookup for a CMS. API keys, bo_live_ and bo_test_, sent as Authorization: Bearer, each with the read, write or admin scope and a budget a minute set by its edition. Cursor pagination. Nine webhook events, signed with HMAC-SHA256, with a delivery log and replay. And test mode, a bo_test_ key reading fictional organisations and changing nothing.

   The OpenAPI 3.1 document is published at /docs/openapi.json and /docs/openapi.yaml, generated from the same schemas the API validates against.

   The statements on these pages that the API was not available yet are removed, as the entry before this one said the next entry would record.

2. API documentation published. The API itself is not available yet

   Added · 18 September 2026

   The documentation section is live at /docs. The public API is not: there is no base URL to call, no keys to create, and no endpoint behind any path named in it.

   What is published now are the commitments an integration is designed around, and they are settled: cursor pagination and its page sizes, the rate-limit headers on every response, the whole error model — which is in service today and is the same module the public API will answer with — and the versioning policy.

   What is held back is anything that would be copied and run: the OpenAPI document, the quickstart, the worked example, the endpoint reference and webhooks. Each of those is a route with a statement on it saying what it will carry.

   The next entry here is the one that removes those statements.

What will not change

/api/v1/ is stable. Additive changes only — new fields, new endpoints, new optional parameters. A breaking change means /api/v2/, with both live for at least 12 months.

An entry that would contradict that sentence is not an entry in this list. It is a /api/v2/ entry, and both versions answer for at least 12 months while you move.

How a deprecation is announced

• A deprecated endpoint sends a Sunset header, per RFC 8594, naming the date it stops working.
• The changelog entry is written when the deprecation is decided, not when it ships, and it carries both dates: the day the header starts being sent and the day the endpoint stops answering.
• Documentation for a deprecated endpoint stays up until the endpoint is removed. Removing the page first is how an integrator finds out by breaking.

The order matters more than the mechanism. An endpoint whose documentation disappears before the endpoint does is one you find out about by breaking, and a budget cycle is long enough that a year of notice is sometimes barely enough.

Subscribing

The feed is at /docs/changelog.xml, as RSS. It carries the same entries as this page, with the same categories and the same dates, and it is declared in this page’s head so a reader that looks for one finds it without your typing the address.

There is nothing to sign up for and no address to give us. That is deliberate: the people who most need to know when an endpoint changes are the ones least able to get a marketing subscription past their own procurement.