REST: Admin, other

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).

List audit log entries

GET /api/admin/audit-log

Newest first, filtered and paged by id. Requires the View audit log permission (the Owner always has it). What a reader sees depends on the entry's class (doc/moderation.md): sign-in events, webhooks, system, media, settings and Owner-only account actions are only returned to the Owner and Administrators, and message, Talk and forum entries only for channels the caller can view; an action the class table does not name is only returned to the Owner and Administrators. Entries are immutable. Secrets are never stored; message deletions and edits keep the message text.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
actorquerystring (uuid)noActor user id.
actionquerystringnoExact action (role.update) or a group (role matches every role.*).
target_typequerystringnoTarget type, e.g. user, role, channel.
target_idquerystringnoTarget id.
fromquerystring (date-time)noOnly entries at or after this time (RFC 3339 or YYYY-MM-DD).
toquerystring (date-time)noOnly entries before this time (RFC 3339 or YYYY-MM-DD, end of day).
beforequeryintegernoEntries with a smaller id only (the previous page's next_before).
limitqueryintegernoPage size, 1-200.

Responses

StatusMeaningBody
200Entries.Page
400Invalid input (INVALID_INPUT): malformed filter.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the View audit log permission.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Page
FieldTypeDescription
entries (required)Item[]
next_before (required)integer | nullNextBefore is the value of the before parameter that fetches the next page; null on the last page.

List bans

GET /api/admin/bans

Active bans, newest first. Needs Ban members.

Authentication: Session cookie

Responses

StatusMeaningBody
200Bans.Ban[]
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Ban members permission.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Create a category

POST /api/admin/categories

Requires the Manage channels permission (403 otherwise).

Authentication: Session cookie

Request body (application/json, required): CreateCategoryRequest

FieldTypeDescription
name (required)string
sort_orderinteger

Responses

StatusMeaningBody
201Created category.Category
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: missing the Manage channels permission, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Category
FieldTypeDescription
channels (required)Channel[]
created_at (required)string (date-time)
id (required)string (uuid)
name (required)string
sort_order (required)integer

Delete a category

DELETE /api/admin/categories/{id}

Its channels become uncategorized and keep its permission overwrites. A category with overwrites needs the Administrator permission and sight of every channel in it (404 otherwise); 409 when the category and its channels both have overwrites (they cannot be merged exactly). Requires the Manage channels permission (403 otherwise).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Responses

StatusMeaningBody
204Success, no content.
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: missing the Manage channels permission (a category with permission overwrites also needs Administrator), or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Rename a category

PATCH /api/admin/categories/{id}

Requires the Manage channels permission (403 otherwise).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Request body (application/json, required): RenameCategoryRequest

FieldTypeDescription
name (required)string

Responses

StatusMeaningBody
200Renamed category.RenamedCategory
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: missing the Manage channels permission, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
RenamedCategory
FieldTypeDescription
id (required)string (uuid)
name (required)string

Apply category order and channel placement

PUT /api/admin/layout

Applied in one transaction. Requires the Manage channels permission (403 otherwise).

Authentication: Session cookie

Request body (application/json, required): LayoutRequest

FieldTypeDescription
categoriesCategoryOrder[]
channelsChannelPlacement[]

Responses

StatusMeaningBody
204Success, no content.
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: missing the Manage channels permission, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Message settings

GET /api/admin/message-settings

Owner and Administrators: the lifetime switch and ceiling, the community's auto-delete default and when auto-delete runs next. Needs the messages.lifetime feature.

Authentication: Session cookie

Responses

StatusMeaningBody
200The settings.MessageSettingsView
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: not the Owner or an Administrator.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
MessageSettingsView
FieldTypeDescription
auto_delete_default_hours (required)integerAutoDeleteDefaultHours is the period channels without a setting of their own follow; 0 = off.
auto_delete_default_scope (required)stringAutoDeleteDefaultScope is what that default removes.
auto_delete_next_run_at (required)string (date-time)AutoDeleteNextRunAt is when the auto-delete sweeper runs next.
message_lifetime_max_seconds (required)integerLifetimeMaxSeconds is the longest lifetime anybody may choose.
message_lifetimes_enabled (required)booleanLifetimesEnabled lets members send messages with a lifetime.

Set the auto-delete default

PUT /api/admin/message-settings/auto-delete

Owner and Administrators; audited as settings.auto_delete_default_set. Every community channel without an auto-delete setting of its own follows it; conversations and their call Talks never do. hours 0 turns the default off (the initial state). Broadcasts channels_changed. Needs the channels.auto_delete.v2 feature.

Authentication: Session cookie

Request body (application/json, required): AutoDeleteDefaultRequest

FieldTypeDescription
hours (required)integerHours is the community default, 0 (off) to 8760.
scopestringScope is what it removes: "all" (the default) or "attachments".

Responses

StatusMeaningBody
200The settings now.MessageSettingsView
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, hours outside 0 to 8760 or an unknown scope.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: not the Owner or an Administrator, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
MessageSettingsView
FieldTypeDescription
auto_delete_default_hours (required)integerAutoDeleteDefaultHours is the period channels without a setting of their own follow; 0 = off.
auto_delete_default_scope (required)stringAutoDeleteDefaultScope is what that default removes.
auto_delete_next_run_at (required)string (date-time)AutoDeleteNextRunAt is when the auto-delete sweeper runs next.
message_lifetime_max_seconds (required)integerLifetimeMaxSeconds is the longest lifetime anybody may choose.
message_lifetimes_enabled (required)booleanLifetimesEnabled lets members send messages with a lifetime.

Preview the auto-delete default

POST /api/admin/message-settings/auto-delete/preview

Owner and Administrators: a dry run of PUT /api/admin/message-settings/auto-delete with the same body, counted over every channel that follows the default. Changes nothing. Needs the channels.auto_delete.v2 feature.

Authentication: Session cookie

Request body (application/json, required): AutoDeleteDefaultRequest

FieldTypeDescription
hours (required)integerHours is the community default, 0 (off) to 8760.
scopestringScope is what it removes: "all" (the default) or "attachments".

Responses

StatusMeaningBody
200What would be removed.AutoDeletePreview
400Invalid input (INVALID_INPUT): as for setting it.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: not the Owner or an Administrator, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
AutoDeletePreview
FieldTypeDescription
attachments (required)integerAttachments is how many files would be removed.
messages (required)integerMessages is how many messages would be deleted, thread replies that go with their root included; 0 for the scope "attachments".
next_run_at (required)string (date-time)NextRunAt is when the sweeper runs next.

Set the lifetime settings

PUT /api/admin/message-settings/lifetimes

Owner and Administrators; audited as settings.message_lifetimes_set. Switching lifetimes off refuses new messages with a lifetime; those that have one still end on time. The ceiling holds for everyone, the Owner included. Broadcasts channels_changed. Needs the messages.lifetime feature.

Authentication: Session cookie

Request body (application/json, required): LifetimeSettingsRequest

FieldTypeDescription
message_lifetime_max_secondsinteger | nullMaxSeconds is the new ceiling, 60 to 2592000; absent keeps it.
message_lifetimes_enabledboolean | nullEnabled switches lifetimes on or off; absent keeps it.

Responses

StatusMeaningBody
200The settings now.MessageSettingsView
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields or a ceiling outside 60 to 2592000.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: not the Owner or an Administrator, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
MessageSettingsView
FieldTypeDescription
auto_delete_default_hours (required)integerAutoDeleteDefaultHours is the period channels without a setting of their own follow; 0 = off.
auto_delete_default_scope (required)stringAutoDeleteDefaultScope is what that default removes.
auto_delete_next_run_at (required)string (date-time)AutoDeleteNextRunAt is when the auto-delete sweeper runs next.
message_lifetime_max_seconds (required)integerLifetimeMaxSeconds is the longest lifetime anybody may choose.
message_lifetimes_enabled (required)booleanLifetimesEnabled lets members send messages with a lifetime.

Operator status

GET /api/admin/status

Operator status overview: server version, update state, database and storage stats, backup state, activity counts and warnings. Owner or Administrator only (403 otherwise).

Authentication: Session cookie

Responses

StatusMeaningBody
200Operator status overview.OperatorStatus
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
OperatorStatus
FieldTypeDescription
activity (required)ActivityStatus
auto_deploy (required)SelfUpdateStatus
backup (required)BackupStatus
database (required)DatabaseStatus
disk_free_bytesinteger
setup (required)Check[]Setup is the setup checklist: green, amber and red items, each red or amber one naming the variable to set.
storage (required)StorageStatus
update (required)UpdateStatus
version (required)SystemVersion
warnings (required)Warning[]

Server capacity

GET /api/admin/status/capacity

Live CPU, memory and media rates of the server over the last minute, an estimate of how many more members it can take, each watching a screen share, and per usage scenario how many people one Talk can hold, with the resource that runs out first. The estimate uses the cost model of doc/benchmark.md, scaled by this host's observed CPU per packet when there is enough traffic; it is an estimate for planning, not a promise. Owner or Administrator only (403 otherwise).

Authentication: Session cookie

Responses

StatusMeaningBody
200Capacity figures and estimate.CapacityStatus
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
CapacityStatus
FieldTypeDescription
collecting (required)booleanCollecting is true in the first seconds after the start, before the sampler has taken a measurement: the figures are not real yet.
cpu_cores (required)numberCPUCores is the CPU the server may use; CPUUsedCores what it used over the last minute.
cpu_used_cores (required)number
egress_mbps (required)numberEgressMbps is the media the server sends, averaged over the last minute.
egress_pps (required)integer
estimate (required)CapacityEstimateEstimate is the planning estimate (see doc/benchmark.md).
heap_bytes (required)integer
ingress_pps (required)integer
memory_limit_bytes (required)integerMemoryLimitBytes is the container limit (APP_MEM_LIMIT); 0 when unknown.
peers (required)integerPeers are media connections now; ScreenShares live screen shares.
rss_bytes (required)integer
screen_shares (required)integer

Report the admin's WebSocket

POST /api/admin/status/websocket

The admin page tells the server whether its own /api/ws connection came through the reverse proxy as an upgraded WebSocket. The Status tab shows the outcome as the WebSocket item. Owner or Administrator only (403 otherwise).

Authentication: Session cookie

Request body (application/json, required): WebSocketReport

FieldTypeDescription
connected (required)booleanConnected is whether the admin's own /api/ws connection is open and upgraded.

Responses

StatusMeaningBody
204Recorded.
400Invalid input (INVALID_INPUT): malformed body.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Something wrong on this page? Tell us.