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

SurfaceWhere it is definedWhat is covered
REST API under /api/api/openapi.json, generated by make openapiPaths, methods, parameters, request and response bodies, status codes, error codes, authentication (cookie session, bot token).
WebSocket eventsinternal/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.tsThe event names in both directions and the fields of their payloads.
Bot gateway and bot APIbots.mdOpcodes, intents, dispatch names and payloads, bot REST routes, slash commands and interactions.
Desktop client contractweb_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.mdThe integer a bundle and a server agree on, the manifest fields, the verification rules.
Desktop bridgeThe Platform interface in web/src/shared/lib/platform.ts, plus the host commands and window globals behind it, which the desktop client repository implementsMethod names and shapes, command names and their arguments and results.
Environment variables.env.example and operations.mdNames, meaning and default values of documented variables.
Metric namesoperations.md (GET /api/metrics)Metric names, types and label names.
Backup layoutoperations.mdWhat 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_seconds is the public talk time only (stays in Talks that @everyone can see) and restarts at 0 with this release. It applies to GET /api/users/{id}, the member list and the user_stats event. The private total stays in the database and the data export.
  • message_count on 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 answers 404.
  • Bulk PUT /api/bot/v1/commands keeps the commands an admin disabled and counts them toward the 50-command cap; over the cap it answers 400.
  • A gateway session is closed with 4014 when the allowed intents shrink below what it asked for.
  • DELETE /api/events/{id}/signup on an event the caller cannot see, or without a sign-up, answers 404.
  • A search, mentions or forum cursor that points at something the caller cannot see answers 404.
  • Moderation notes (POST, PUT) answer 403 for 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}/messages accepts an optional nonce (UUID). A second send of the same nonce by the same author answers 200 with the first message; if that message was deleted since, 410 with code MESSAGE_DELETED; a nonce already used in another channel is 400. Nonces are kept for 24 hours.
  • The nonce is part of the message in the message_create event, the bot gateway's MESSAGE_CREATE and the outgoing webhook payload.

Additions

  • GET /api/admin/reports/open-count and the WebSocket event reports_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 example GET /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 Platform method 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 a BREAKING 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 Deprecation header and, once a removal date is known, a Sunset header (RFC 9745, RFC 8594), and the OpenAPI operation gets deprecated: 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.
  • 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_api is 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_version and security_floor follow 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_api and 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_id optional in GET /api/admin/reports, GET /api/admin/reports/{id} and POST /api/admin/reports/{id}/resolve (automod entries have no message) — a breaking change in a minor release, announced via the BREAKING 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 the backend CI job and make check) compares api/openapi.json with the one at the latest stable v* tag using a pinned oasdiff and fails on every error-level change. It is waived only when a commit of the change carries a BREAKING CHANGE: footer, which is how a major release lands. The script is scripts/openapi_diff.py and has tests in scripts/tests/. It filters no oasdiff rule; a rule that reports generator noise is listed in IGNORED_RULES there, 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, and npm run contracts:check fails when the registry and web/src/types/events.ts disagree.
  • Desktop client: web/desktop-compat.json and the server's web_client_api are 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 what v1.0.0, v2.0.0, v2.9.12 and v2.9.18 promised (OpenAPI contract, health features, events; made by node scripts/compat-baseline.ts <tag>... in web/) and runs the app's own stores and forms against it in the normal vitest run: 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 in web/src/compat/allowlist.ts that 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.

Something wrong on this page? Tell us.