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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
actor | query | string (uuid) | no | Actor user id. |
action | query | string | no | Exact action (role.update) or a group (role matches every role.*). |
target_type | query | string | no | Target type, e.g. user, role, channel. |
target_id | query | string | no | Target id. |
from | query | string (date-time) | no | Only entries at or after this time (RFC 3339 or YYYY-MM-DD). |
to | query | string (date-time) | no | Only entries before this time (RFC 3339 or YYYY-MM-DD, end of day). |
before | query | integer | no | Entries with a smaller id only (the previous page's next_before). |
limit | query | integer | no | Page size, 1-200. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Entries. | Page |
| 400 | Invalid input (INVALID_INPUT): malformed filter. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the View audit log permission. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Page
| Field | Type | Description |
|---|---|---|
entries (required) | Item[] | |
next_before (required) | integer | null | NextBefore 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Bans. | Ban[] |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Ban members permission. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Field | Type | Description |
|---|---|---|
name (required) | string | |
sort_order | integer |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created category. | Category |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage channels permission, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Category
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage channels permission (a category with permission overwrites also needs Administrator), or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Rename a category
PATCH /api/admin/categories/{id}
Requires the Manage channels permission (403 otherwise).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource ID. |
Request body (application/json, required): RenameCategoryRequest
| Field | Type | Description |
|---|---|---|
name (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Renamed category. | RenamedCategory |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage channels permission, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
RenamedCategory
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
categories | CategoryOrder[] | |
channels | ChannelPlacement[] |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage channels permission, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | MessageSettingsView |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: not the Owner or an Administrator. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
MessageSettingsView
| Field | Type | Description |
|---|---|---|
auto_delete_default_hours (required) | integer | AutoDeleteDefaultHours is the period channels without a setting of their own follow; 0 = off. |
auto_delete_default_scope (required) | string | AutoDeleteDefaultScope 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) | integer | LifetimeMaxSeconds is the longest lifetime anybody may choose. |
message_lifetimes_enabled (required) | boolean | LifetimesEnabled 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
| Field | Type | Description |
|---|---|---|
hours (required) | integer | Hours is the community default, 0 (off) to 8760. |
scope | string | Scope is what it removes: "all" (the default) or "attachments". |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings now. | MessageSettingsView |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, hours outside 0 to 8760 or an unknown scope. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: not the Owner or an Administrator, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
MessageSettingsView
| Field | Type | Description |
|---|---|---|
auto_delete_default_hours (required) | integer | AutoDeleteDefaultHours is the period channels without a setting of their own follow; 0 = off. |
auto_delete_default_scope (required) | string | AutoDeleteDefaultScope 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) | integer | LifetimeMaxSeconds is the longest lifetime anybody may choose. |
message_lifetimes_enabled (required) | boolean | LifetimesEnabled 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
| Field | Type | Description |
|---|---|---|
hours (required) | integer | Hours is the community default, 0 (off) to 8760. |
scope | string | Scope is what it removes: "all" (the default) or "attachments". |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | What would be removed. | AutoDeletePreview |
| 400 | Invalid input (INVALID_INPUT): as for setting it. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: not the Owner or an Administrator, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
AutoDeletePreview
| Field | Type | Description |
|---|---|---|
attachments (required) | integer | Attachments is how many files would be removed. |
messages (required) | integer | Messages 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
| Field | Type | Description |
|---|---|---|
message_lifetime_max_seconds | integer | null | MaxSeconds is the new ceiling, 60 to 2592000; absent keeps it. |
message_lifetimes_enabled | boolean | null | Enabled switches lifetimes on or off; absent keeps it. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings now. | MessageSettingsView |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields or a ceiling outside 60 to 2592000. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: not the Owner or an Administrator, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
MessageSettingsView
| Field | Type | Description |
|---|---|---|
auto_delete_default_hours (required) | integer | AutoDeleteDefaultHours is the period channels without a setting of their own follow; 0 = off. |
auto_delete_default_scope (required) | string | AutoDeleteDefaultScope 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) | integer | LifetimeMaxSeconds is the longest lifetime anybody may choose. |
message_lifetimes_enabled (required) | boolean | LifetimesEnabled 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Operator status overview. | OperatorStatus |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
OperatorStatus
| Field | Type | Description |
|---|---|---|
activity (required) | ActivityStatus | |
auto_deploy (required) | SelfUpdateStatus | |
backup (required) | BackupStatus | |
database (required) | DatabaseStatus | |
disk_free_bytes | integer | |
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
| Status | Meaning | Body |
|---|---|---|
| 200 | Capacity figures and estimate. | CapacityStatus |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
CapacityStatus
| Field | Type | Description |
|---|---|---|
collecting (required) | boolean | Collecting 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) | number | CPUCores is the CPU the server may use; CPUUsedCores what it used over the last minute. |
cpu_used_cores (required) | number | |
egress_mbps (required) | number | EgressMbps is the media the server sends, averaged over the last minute. |
egress_pps (required) | integer | |
estimate (required) | CapacityEstimate | Estimate is the planning estimate (see doc/benchmark.md). |
heap_bytes (required) | integer | |
ingress_pps (required) | integer | |
memory_limit_bytes (required) | integer | MemoryLimitBytes is the container limit (APP_MEM_LIMIT); 0 when unknown. |
peers (required) | integer | Peers 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
| Field | Type | Description |
|---|---|---|
connected (required) | boolean | Connected is whether the admin's own /api/ws connection is open and upgraded. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Recorded. | |
| 400 | Invalid input (INVALID_INPUT): malformed body. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: only the Owner and members with the Administrator permission may do this. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |