REST: Admin, system

Management endpoints. Each operation names the permission it needs: Owner only, a permission such as Manage members, Ban members or Manage channels, or the Administrator permission. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

System status

GET /api/admin/system

Version, health and load of the server for the admin System tab. Contains no secrets. Owner only (403 otherwise).

Authentication: Session cookie

Responses

StatusMeaningBody
200System status.SystemStatus
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
SystemStatus
FieldTypeDescription
health (required)SystemHealth
mail (required)MailStatusMail is the outgoing mail setup (account e-mails need it).
self_update (required)SelfUpdateStatus
update (required)UpdateStatus
version (required)SystemVersion
warnings (required)Warning[]Warnings are configuration or deployment problems the server noticed (stable codes; the web app explains each). Empty when all is well.

Check for a new release now

POST /api/admin/system/check

Asks GitHub for the latest release right away (at most once a minute; while GitHub rate-limits the server, 429 until that ends). 409 when UPDATE_CHECK_ENABLED=false. A failed check still answers 200 with check_error set. Owner only (403 otherwise).

Authentication: Session cookie

Responses

StatusMeaningBody
200Update status after the check.UpdateStatus
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, or cross-origin request rejected.ErrorResponse
409CONFLICT: the update check is disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
UpdateStatus
FieldTypeDescription
check_enabled (required)booleanCheckEnabled is false with UPDATE_CHECK_ENABLED=false (no requests to GitHub).
check_error (required)stringCheckError says why the last check failed (empty when it worked).
checked_at (required)string | null
current_version (required)string
latest_version (required)stringLatestVersion is empty until a check succeeded.
published_at (required)string | null
release_notes (required)stringReleaseNotes is Markdown; clients render it as untrusted text.
release_url (required)stringReleaseURL is the release page on github.com.
retry_at (required)string | nullRetryAt is set while GitHub's rate limit pauses the checks.
update_available (required)boolean

Send a test e-mail

POST /api/admin/system/mail/test

Sends a short message through the configured SMTP server to show that mail works. The recipient defaults to the Owner's own address (set one under the account settings) and can be given explicitly. Owner only (403 otherwise); at most five per ten minutes. The audit entry names no recipient. The failure answer says which stage failed (connect, tls, auth, sender, recipient, data), never a server reply or a credential.

Authentication: Session cookie

Request body (application/json): TestMailRequest

FieldTypeDescription
tostring (email)To is the recipient; it defaults to the Owner's own e-mail address.

Responses

StatusMeaningBody
204Test mail sent.
400Invalid input (INVALID_INPUT): no valid recipient, or SMTP is not configured.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: the mail could not be delivered; the message names the failing stage.ErrorResponse

Operator metrics

GET /api/admin/system/ops

Live counters and a short history (last hour, 10 s resolution) for the admin System tab. Contains no secrets and no user or channel ids. Owner only (403 otherwise).

Authentication: Session cookie

Responses

StatusMeaningBody
200Operator metrics.OpsStatus
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
OpsStatus
FieldTypeDescription
db_pool (required)OpsPool
history (required)OpsSample[]History holds up to the last hour of samples, oldest first.
interval_seconds (required)integerIntervalSeconds is the spacing of History.
process (required)OpsProcess
totals (required)OpsTotals

Update status

GET /api/admin/system/update

What the last release check found (cheap: no request to GitHub). Owner only (403 otherwise).

Authentication: Session cookie

Responses

StatusMeaningBody
200Update status.UpdateStatus
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
UpdateStatus
FieldTypeDescription
check_enabled (required)booleanCheckEnabled is false with UPDATE_CHECK_ENABLED=false (no requests to GitHub).
check_error (required)stringCheckError says why the last check failed (empty when it worked).
checked_at (required)string | null
current_version (required)string
latest_version (required)stringLatestVersion is empty until a check succeeded.
published_at (required)string | null
release_notes (required)stringReleaseNotes is Markdown; clients render it as untrusted text.
release_url (required)stringReleaseURL is the release page on github.com.
retry_at (required)string | nullRetryAt is set while GitHub's rate limit pauses the checks.
update_available (required)boolean

Update the server now

POST /api/admin/system/update

Asks the optional updater sidecar (compose profile autoupdate, UPDATER_TOKEN) to verify the new release image (cosign signature and build provenance of this project's release workflow), pull exactly that digest and restart the app; everyone is disconnected for about 30-60 seconds. Admin only, same-origin only, re-authenticates with the admin's current password (5 wrong passwords lock the action like a password change does), at most once per 5 minutes, only while a newer release is known and target_version names it. Audit-logged. Owner only (403 otherwise).

Authentication: Session cookie

Request body (application/json, required): SelfUpdateRequest

FieldTypeDescription
password (required)string (password)Password is the admin's current password (re-authentication).
target_version (required)stringTargetVersion must equal the latest release the server knows, so a dialog opened before a newer release can't start the wrong update.

Responses

StatusMeaningBody
202The updater accepted the request.SelfUpdateStarted
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, the current password is wrong, or cross-origin request rejected.ErrorResponse
409CONFLICT: self-update not configured, no update available, target_version outdated, the image tag cannot reach the release, the image repository moved (moved_to), or an update is already running.ErrorResponse
429RATE_LIMITED: an update was requested less than 5 minutes ago, or too many wrong passwords.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: the updater is not reachable, rejected the request, or refused the new image because its signature or provenance did not verify (nothing was changed).ErrorResponse
SelfUpdateStarted
FieldTypeDescription
from_version (required)string
status (required)string
target_version (required)string

Something wrong on this page? Tell us.