API stability and versions¶
Look up what can change in Narad's /v1 HTTP API, how nodes on different releases work together, and which release these docs describe.
Changes within /v1¶
Within /v1, the routes, parameters, status codes and JSON field names in the HTTP API reference do not change meaning and do not go away. What can appear:
- new optional request fields and parameters;
- new fields in responses;
- new endpoints.
So a client should ignore response fields it does not know. Request bodies stay strict: a field the server does not know gets 400, which is how an older node refuses a field it cannot honour instead of dropping it silently.
A change that has to break the contract goes to a new /v2 prefix, and both versions are served side by side for a deprecation period.
Node-to-node protocol¶
Nodes talk to each other over a versioned protocol under the same rule. Operation codes are only ever added. New fields are optional and go at the end of a message. A node that does not know a new field answers with a clean 400, and the sender retries in the older shape. That is what lets a cluster run two releases side by side during a rolling upgrade. The two operations remote replication adds in v3.2.0 have no older shape; they are refused with 412 until every member runs the release that knows them. Release-specific conditions, such as the config keys an older binary refuses, are in Upgrade Narad.
Which release these docs describe¶
These docs follow master. The latest release is v3.2.2, tagged on 8 October 2026.
Anything v3.2.0 added carries this line under its heading:
New in v3.2.0.
In a table, the item's name ends in "(v3.2.0)", and in a sentence the change is marked "(from v3.2.0)". What v3.1.0 added is marked the same way with its own version.
Work merged to master after v3.2.2 is marked unreleased until it ships: in a table, its name ends in "(unreleased)", and under its heading it carries this line:
Unreleased: in master, not in v3.2.2.
When the next release ships, those markers name that release instead. The changelog lists every change by release.
What a v3.0.1 node does with the HTTP features v3.1.0 added, checked against a v3.0.1 build:
| Feature | A v3.0.1 node |
|---|---|
Batch produce, POST /v1/topics/{topic}/produce/batch |
answers 404 |
Batch consume, GET .../consume?max=N |
ignores max and answers with one message, in the single-message shape |
Batch ack, a receipt_handles body |
answers 400 (receipt_handle required) |
| A produce without a key | stores an invented key, key-<n>, which consumers see |
http. in the config file |
refuses to start with an unknown field error |
storage. or storage.ingress_wal_prealloc in the config file |
refuses to start: the key is an internal setting there and cannot be configured |
A client that must work against both releases can send single produces, consumes and acks, and should always send a key when it relies on seeing one. To find the release a node runs, read the image tag it was deployed with: narad version on a v3.0.1 image prints a commit, not a version number.