API & wire versioning
How the BRN0 wire-protocol version is negotiated, and what stability means for Brain pre-1.0.
There is no API-version header
Brain does not date-stamp its API or take an X-Api-Version / version-pin
header. It has one current protocol, and back-compat shims are deliberately
absent while the system is pre-1.0 (see pre-1.0 below).
Requests carry only the credential:
POST /v1/recall HTTP/1.1
Authorization: Bearer <key>
Content-Type: application/jsonX-API-Key: <key> is accepted as an alternative to Authorization: Bearer.
There are no other version or scope headers to send — the server derives the
caller's (namespace, agent, permissions) from the key alone.
Wire-protocol version negotiation
The native wire client (BrainClient) speaks the BRN0 binary protocol. Its
version is negotiated once, at connection time: the client offers the versions
it supports in the handshake and the server picks one, returned in the
WELCOME frame. A client that offers nothing the server supports gets a
VersionMismatch (carrying chosen and supported) rather than a silent
downgrade.
You don't set this by hand — the SDK offers what it was built for. Match the SDK version to the server you connect to (they ship in lockstep pre-1.0).
Pre-1.0 stability
Brain is 0.1.0, pre-release, with no external users. The wire protocol, the
redb table layout, and the HTTP surface are still in flux. Breaking changes
are made in place — no dated versions to migrate between, no deprecation
window, no compatibility aliases. Pin the SDK version you build against and
upgrade the client and server together.
The v1.0 release is the next milestone. Once it ships, the intended contract is conventional: additive changes (new optional fields, new endpoints, new verbs) are non-breaking and land in minors; removing or renaming a field, changing a type, tightening validation, or adding a required field is breaking and waits for a new major with migration notes.
Self-hosting
When you self-host, the API and wire protocol are whatever the running
brain-server build supports. Keep the SDK and the server on matching versions;
because there is no negotiated fallback across pre-1.0 protocol revisions, a
mismatched pair surfaces as a VersionMismatch at connect time rather than
misbehaving at runtime.
Was this page helpful?