The contract¶

The four MeshBee components ship independently. What keeps them interoperable is this contract: the MQTT payload format and the HTTP API. It is deliberately small, explicit, and versioned.

This site is its single home. The artifacts below live at stable URLs that other repos can link to. Release notes should point here rather than paste a copy — a duplicated spec is a spec that goes stale without anyone noticing.

English only, by design

Contract pages are not translated. They describe machine-facing specs and schemas, where a second wording is a second source of truth waiting to disagree with the first.

Artifacts¶

Artifact	Where it comes from
API reference	Generated by `meshbee-server`, rendered with Scalar live from that repo's `main` branch
MQTT payload	JSON Schema generated by `meshbee-server`, read live from that repo's `main` branch
Compatibility matrix	Maintained here by hand — it's a record of what was field-tested together

Direct links to the raw files:

How the artifacts stay current¶

Both machine-readable artifacts are generated, never hand-written, and neither is copied here. They live in meshbee-server — api/openapi.json regenerated by make openapi, and mqtt_handler/mqtt-payload.schema.json regenerated by make mqtt-schema from the pydantic model in mqtt_handler/contract.py. Each is read straight from that repository's main branch: the API reference fetches the spec when your browser loads the page, and the MQTT schema's own $id is its raw URL, so a $ref in a firmware toolchain resolves there too.

There is deliberately no copy of either in this repository. A duplicated spec is a spec that goes stale without anyone noticing, and the whole point of publishing one home for the contract is that there is only one file to be right. These pages are the prose; upstream holds the artifacts.

Two consequences worth knowing:

Both track main, not the latest release — including changes that have not shipped yet. Read the compatibility matrix when you need to know what a given release actually speaks.
Nothing here needs rebuilding when the contract changes. A regenerated artifact is live the moment it lands on main upstream; this site only needs a build when these pages change.

Because the schema's $id names its path in meshbee-server, moving or renaming that file breaks every $ref written against it — upstream treats the path as part of the contract.

What is not versioned yet¶

The pages here describe the interface as it ships today. Two parts of the intended versioning scheme are not implemented: the MQTT payload carries no version integer, and the HTTP API is served under /api/… with no version segment in the path. Both are documented as design intent on the MQTT payload page and in Architecture, and clearly marked as such. The compatibility matrix is real and maintained.