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

StatusMeaningBody
200The API reference page.string
302No 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

StatusMeaningBody
200Healthy.Health
503UNAVAILABLE: a dependency (database, file storage) is not available.HealthUnavailable
Health
FieldTypeDescription
community_iconstringCommunityIcon 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_namestringCommunityName 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.
featuresstring[]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_urlstringPublicURL 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)integerWebClientAPI 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

StatusMeaningBody
200The process serves requests.Liveness
Liveness
FieldTypeDescription
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

StatusMeaningBody
200Legal information.Legal
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Legal
FieldTypeDescription
address_detection (required)booleanAddressDetection 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)booleanBuiltinTURN 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)integerMediaRetentionDays 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)booleanUpdateCheck 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

StatusMeaningBody
200Prometheus text exposition format.string
401Missing or wrong bearer token (plain text 'unauthorized', WWW-Authenticate: Bearer).string
500INTERNAL_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

StatusMeaningBody
200The OpenAPI document.object
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse

Something wrong on this page? Tell us.