API stability
From mnema-talk v3.3.13, rendered on this site.
Mnema Talk follows semantic versioning for the surfaces
listed here. A client, bot, webhook consumer, dashboard or alert that works
against 3.x keeps working against every later 3.y and 3.y.z. Only a new
major version (4.0.0) may remove or change them incompatibly, and it says so
in the changelog. The same promise held for 1.x and 2.x; 3.0.0 is the
major release that carries the changes listed in 3.0.0 changes.
This page is the contract. If something is not on the public list, it can change in any release.
What is public
| Surface | Where it is defined | What is covered |
|---|---|---|
REST API under /api/ | api/openapi.json, generated by make openapi | Paths, methods, parameters, request and response bodies, status codes, error codes, authentication (cookie session, bot token). |
| WebSocket events | internal/events/types.go, pinned by internal/events/testdata/events.golden.json; payload shapes in api/events.json, derived from the Go event types and pinned byte for byte by the event_wire_* golden tests; the web app's types in web/src/types/events.ts | The event names in both directions and the fields of their payloads. |
| Bot gateway and bot API | bots.md | Opcodes, intents, dispatch names and payloads, bot REST routes, slash commands and interactions. |
| Desktop client contract | web_client_api and the compat fields in web/desktop-compat.json (min_server_version, security_floor), the signed bundle manifest, GET /api/health; desktop-trusted-client.md | The integer a bundle and a server agree on, the manifest fields, the verification rules. |
| Desktop bridge | The Platform interface in web/src/shared/lib/platform.ts, plus the host commands and window globals behind it, which the desktop client repository implements | Method names and shapes, command names and their arguments and results. |
| Environment variables | .env.example and operations.md | Names, meaning and default values of documented variables. |
| Metric names | operations.md (GET /api/metrics) | Metric names, types and label names. |
| Backup layout | operations.md | What the backup and restore scripts write and read. |
GET /api/health answers 200 or 503; the 503 carries the same fields as
the 200 beside its error, with status unavailable and the dependencies
that are down in unavailable (an older server sends the error alone, so a
client reads the fields only when they are there). The names in unavailable
are database and storage today; the list may grow in a later release, so a
client ignores a name it does not know. GET /api/health/live is
the liveness probe and never depends on the database or object storage.
GET /api/health also carries public_url, the server's PUBLIC_URL (left out
when none is set). A client that is not served from that address, such as the
desktop app, builds the links it shares (invites, message links) from it.
GET /api/health also lists the optional features a server has in features. A name never changes meaning and is never removed within a major version; a client treats a missing list as "none" (a 1.0.x server sends no list) and hides what is not listed. A new feature adds a name, never a web_client_api bump.
Permission bits are public too. 1.1 added Manage reports (1 << 21), Send
direct messages (1 << 22) and Kick members (1 << 23); 1.2 adds Manage
stage (1 << 24) and Manage events (1 << 25). The meaning of a
bit never changes (roles and permissions).
Documented behaviour is part of the contract, such as permission checks, limits
that the OpenAPI document or the docs state, and the default of
MEDIA_RETENTION_DAYS=0.
3.0.0 changes
3.0.0 is a major release, so it may change documented behaviour. A client,
bot or webhook consumer written against 2.x should check these points; none
renames or removes a path or a field, and every addition is optional.
Values that mean something different
voice_secondsis the public talk time only (stays in Talks that@everyonecan see) and restarts at 0 with this release. It applies toGET /api/users/{id}, the member list and theuser_statsevent. The private total stays in the database and the data export.message_counton a profile excludes direct messages and the chat of a conversation's call, and subtracts channels the viewer cannot see.
Status codes and refusals
- Bot
DELETE /api/bot/v1/commands/{id}of a command an admin disabled answers404. - Bulk
PUT /api/bot/v1/commandskeeps the commands an admin disabled and counts them toward the 50-command cap; over the cap it answers400. - A gateway session is closed with
4014when the allowed intents shrink below what it asked for. DELETE /api/events/{id}/signupon an event the caller cannot see, or without a sign-up, answers404.- A search, mentions or forum cursor that points at something the caller cannot
see answers
404. - Moderation notes (
POST,PUT) answer403for the Owner and for a member the caller does not outrank. - A reaction in a blocked 1:1 direct message answers
403.
Delivery
- Events of a conversation's call (its chat and its call messages) no longer reach bots (gateway, bot API) or outgoing webhooks.
Messages: idempotent send
POST /api/channels/{id}/messagesaccepts an optionalnonce(UUID). A second send of the same nonce by the same author answers200with the first message; if that message was deleted since,410with codeMESSAGE_DELETED; a nonce already used in another channel is400. Nonces are kept for 24 hours.- The
nonceis part of the message in themessage_createevent, the bot gateway'sMESSAGE_CREATEand the outgoing webhook payload.
Additions
GET /api/admin/reports/open-countand the WebSocket eventreports_open(sent to members holding Manage reports) carry the number of open reports.- The data export gains
public_voice_seconds. - The admin status response gains backup and capacity fields (operator view, not part of the stable surface above).
What is not public
These change whenever the code needs it, also in a patch release:
- The database schema and the migrations. Upgrade through the application, never by reading or writing tables from outside. Backups and restores go through the scripts.
- Internal packages (
internal/...) and their Go APIs. The repository is not a library. - Debug and operator-only endpoints: everything under
/api/admin/that the OpenAPI document marks as admin-only and that serves the admin UI (for exampleGET /api/admin/system/ops), the API docs page. - Log formats and messages, including the text of structured fields.
- Anything undocumented: extra fields in a response that no schema lists, the order of array members the documentation does not sort, timing.
- UI: layout, text, translations, CSS and the structure of the web app's
modules (
web/src/...) other than the interfaces above.
What counts as a breaking change
- REST: removing or renaming a path, method, parameter or response field, making an optional request field required, narrowing an enum or a value range, adding a required request field, changing a type, a status code or the authentication a route needs.
- WebSocket: removing or renaming an event, removing or retyping a payload field, or changing when an event is sent so that a client waiting for it never gets it.
- Desktop bridge: removing or renaming a
Platformmethod or host command, changing its arguments or result, or requiring a host feature older desktop clients lack. - Environment variables and metrics: removing or renaming one, or changing a default so that an unchanged deployment behaves differently.
Not breaking: adding an optional request field, a response field, an event, an endpoint, an enum value (clients must ignore what they do not know), a metric or a variable, or widening a value range (a larger maximum a response may carry).
Versioning rules
feat:raises the minor version,fix:the patch version, and a breaking change (!or aBREAKING CHANGE:footer) the major version.- Deprecate first. A public item is deprecated in a minor release. The
deprecation is announced three ways:
- REST routes answer with a
Deprecationheader and, once a removal date is known, aSunsetheader (RFC 9745, RFC 8594), and the OpenAPI operation getsdeprecated: true; - other items (events, variables, bridge methods, metrics) are marked deprecated in their documentation and keep working unchanged;
- the CHANGELOG entry of that release names the item, the replacement and the earliest release that may remove it.
- REST routes answer with a
- Remove only in the next major. A deprecated item stays for at least the rest of the major version it was deprecated in.
web_client_apiis an integer, not a version. It goes up only for an incompatible change of the bridge or of the bundle contract, because a higher number locks older servers out of desktop clients that have seen the new bundle. Compatible additions do not change it.min_server_versionandsecurity_floorfollow the rules in AGENTS.md and desktop-trusted-client.md.- Security fixes may change a public behaviour when a vulnerability cannot be
closed otherwise. The release notes say so, and the change is marked
fix(security):. Example: 1.2.0 stops sending and opening media frame format 2 (RT-4); the REST API, the events,web_client_apiand the health features are untouched, and the clients that can no longer join calls are listed in upgrade.md. - Exceptions in minor releases: 1.2.0 made
message_idoptional inGET /api/admin/reports,GET /api/admin/reports/{id}andPOST /api/admin/reports/{id}/resolve(automod entries have no message) — a breaking change in a minor release, announced via theBREAKING CHANGE:footer; strict third-party clients must treat the field as optional (see upgrade.md).
How it is enforced
- REST:
make openapi-diff(part of thebackendCI job andmake check) comparesapi/openapi.jsonwith the one at the latest stablev*tag using a pinned oasdiff and fails on every error-level change. It is waived only when a commit of the change carries aBREAKING CHANGE:footer, which is how a major release lands. The script isscripts/openapi_diff.pyand has tests inscripts/tests/. It filters no oasdiff rule; a rule that reports generator noise is listed inIGNORED_RULESthere, with the reason. - WebSocket: event names are constants in
internal/events/types.go. A golden-file test fails when one is added, renamed or removed, andnpm run contracts:checkfails when the registry andweb/src/types/events.tsdisagree. - Desktop client:
web/desktop-compat.jsonand the server'sweb_client_apiare checked against each other by tests. The desktop repository pins the bridge side in its own tests. - The web app against older servers: the desktop client loads the web app
of the newest release it has seen and connects to servers back to
min_server_version.web/src/compat/holds whatv1.0.0,v2.0.0,v2.9.12andv2.9.18promised (OpenAPI contract, health features, events; made bynode scripts/compat-baseline.ts <tag>...inweb/) and runs the app's own stores and forms against it in the normalvitestrun: every request body must fit that release's schema (the server rejects unknown fields), every endpoint must exist there, and every answer a release sends must pass the app's decoders. So a new request field, a new endpoint or a new required response field needs a health feature the app waits for, or an entry inweb/src/compat/allowlist.tsthat says what the app does on a server without it (hide the view, fall back to the older route, show the load error). An allowlist entry that is no longer needed fails the test until it is removed. - Everything else is reviewed: a pull request that touches a public surface says so, and the commit type reflects the change.
To change a golden file or waive an OpenAPI break on purpose, the commit message
explains why and carries the BREAKING CHANGE: footer when it needs a major
release.