REST: System
Health, metrics and public information. Generated from mnema-talk v3.3.13 (cca4f0fdb723).
API reference
GET /api/docs
HTML page with Swagger UI over /api/openapi.json. Without a session it redirects to the app (/) to sign in. Only mounted when API_DOCS_ENABLED=true.
Authentication: none
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The API reference page. | string |
| 302 | No session: redirect to /. |
Health check
GET /api/health
Pings the database and checks object storage; the result is cached for 2 s.
A 503 carries the usual error and, beside it, everything the 200 says about the server, plus the dependencies that are down in unavailable.
With only storage in that list, uploads, attachments and pictures fail while chat and Talks keep working. An older server answers a 503 with the error alone.
Authentication: none
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Healthy. | Health |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available. | HealthUnavailable |
Health
| Field | Type | Description |
|---|---|---|
community_icon | string | CommunityIcon is the version of the community icon the Owner set, left out while there is none. GET /api/community/icon serves it (public); the version changes with every upload, so a client refetches when it differs from the one it has. |
community_name | string | CommunityName is what this server calls itself: the name the Owner set in the welcome settings, else the host it is served from. It is public on purpose, so a client can label a server before anyone signs in. |
features | string[] | Features lists the optional features this server has, so a web app of a newer release can hide what an older server lacks (for example "blocks"). A server of 1.0.x sends no list. See doc/api-stability.md. |
public_url | string | PublicURL is the address this server is reached at (PUBLIC_URL), left out when none is configured. A client that is not served from that address, such as the desktop app, builds the links it shares from it. |
status (required) | string | |
version (required) | string | |
web_client_api (required) | integer | WebClientAPI identifies the HTTPS web-client desktop integration contract. |
Liveness check
GET /api/health/live
Answers 200 whenever the process serves requests. It asks neither the database nor object storage, so it stays 200 while GET /api/health answers 503. For orchestrators that restart a container on a failed probe; whether the server is ready for members is what GET /api/health says.
Authentication: none
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The process serves requests. | Liveness |
Liveness
| Field | Type | Description |
|---|---|---|
status (required) | string |
Operator details and privacy-policy facts
GET /api/legal
Public, no session needed. The operator named by the environment, the retention and session lifetimes, the STUN and TURN servers in use and whether the release check is on: the facts the in-app privacy policy states.
Authentication: none
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Legal information. | Legal |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Legal
| Field | Type | Description |
|---|---|---|
address_detection (required) | boolean | AddressDetection is true when the server may ask public STUN servers for its own address at startup (WEBRTC_AUTO_ANNOUNCE); ClockCheck is true when it compares its clock with NTP servers (CLOCK_CHECK_ENABLED). Both reveal only the server's IP address. |
builtin_turn (required) | boolean | BuiltinTURN is true when the TURN relay inside the server process is offered to members (WEBRTC_BUILTIN_TURN); the policy then describes it as part of this server. TURNServers lists the external ones. |
clock_check (required) | boolean | |
legal_version (required) | string | |
media_retention_days (required) | integer | MediaRetentionDays is 0 when media is kept until deleted manually. |
operator_country (required) | string | |
operator_email (required) | string | |
operator_name (required) | string | |
project_notice (required) | string | |
session_expiry_days (required) | integer | |
stun_servers (required) | string[] | |
turn_servers (required) | string[] | |
update_check (required) | boolean | UpdateCheck is true when the server asks GitHub for new releases (UPDATE_CHECK_ENABLED); the privacy policy then names the connection. |
Prometheus metrics
GET /api/metrics
Only registered when METRICS_TOKEN is configured. Failures answer 401 with a plain-text body, not the JSON error shape.
Authentication: Metrics token
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Prometheus text exposition format. | string |
| 401 | Missing or wrong bearer token (plain text 'unauthorized', WWW-Authenticate: Bearer). | string |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
This API description
GET /api/openapi.json
Returns this OpenAPI 3.1 document to signed-in members. Only mounted when API_DOCS_ENABLED=true.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The OpenAPI document. | object |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |