REST: Admin, channels
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).
Create a channel
POST /api/admin/channels
Requires the Manage channels permission (403 otherwise).
Authentication: Session cookie
Request body (application/json, required): CreateChannelRequest
| Field | Type | Description |
|---|---|---|
category_id | string | null | |
is_stage | boolean | IsStage creates the Talk as a Stage (voice channels only). |
name (required) | string | |
sort_order | integer | |
topic | string | |
type | ChannelType |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created channel. | Channel |
| 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 |
Channel
| Field | Type | Description |
|---|---|---|
auto_delete_days | integer | AutoDeleteDays is the effective auto-delete period in days for older clients: whole days rounded down and held within 1 to 90 while it is on (the range they accept), 0 when it is off or deletes only files (auto_delete_scope "attachments"). Never set on direct messages. auto_delete_hours is the precise value (doc/timed-messages.md). |
auto_delete_follows_default | boolean | AutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off). |
auto_delete_hours | integer | AutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay. |
auto_delete_scope | string | AutoDeleteScope is what the period removes: "all" the messages with their files, "attachments" only the files. |
category_id (required) | string | null | |
created_at (required) | string (date-time) | |
id (required) | string (uuid) | |
is_lobby | boolean | IsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md). |
is_stage | boolean | IsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md). |
is_temp | boolean | IsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty. |
leader_id | string (uuid) | LeaderID is the leader of a temporary Talk: the member who may rename it and set its member limit. Absent on every other channel. |
name (required) | string | |
number (required) | integer | Number is the channel's short, stable link number (/c/12-general). |
previous_slugs | string[] | PreviousSlugs are the slugs the channel had before a rename, oldest first. Old links resolve through them; no other channel ever takes one. |
slow_mode_seconds (required) | integer | SlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt. |
slug | string | Slug is the channel's address in the web app (/c/general, /v/lounge): unique server-wide, lowercase ASCII. The id stays the key everywhere. |
sort_order (required) | integer | |
topic (required) | string | |
type (required) | ChannelType | |
user_limit (required) | integer | UserLimit is the most members a voice channel admits at once; 0 = no limit. |
Delete a channel
DELETE /api/admin/channels/{id}
Cascades to its messages and attachments; everyone in a deleted voice channel is disconnected from it. 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, 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 channel, change its topic or member limit
PATCH /api/admin/channels/{id}
Requires the Manage channels permission (403 otherwise). user_limit (voice channels only) caps how many members can be in the room at once; 0 removes the limit (the default). A member already in the room always gets back in. is_lobby (permanent voice channels only) makes the Talk a Create-a-Talk lobby. is_stage (permanent voice channels that are no lobby) makes it a Stage, or a normal Talk again.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource ID. |
Request body (application/json, required): UpdateChannelRequest
| Field | Type | Description |
|---|---|---|
is_lobby | boolean | IsLobby marks a voice channel as a Create-a-Talk lobby (true) or clears the mark (false): joining a lobby opens a temporary Talk (doc/talks.md). |
is_stage | boolean | IsStage turns a permanent Talk into a Stage (true) or back into a normal Talk (false); members without talk power lose their microphone, camera and screen at once (doc/talks.md). |
name | string | |
slow_mode_seconds | integer | SlowModeSeconds sets the least time between two messages of one member in the channel (0 turns slow mode off). Members who may manage messages in the channel are exempt. |
topic | string | |
user_limit | integer | UserLimit caps a voice channel's members at once; 0 removes the limit. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated channel. | Channel |
| 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 |
Channel
| Field | Type | Description |
|---|---|---|
auto_delete_days | integer | AutoDeleteDays is the effective auto-delete period in days for older clients: whole days rounded down and held within 1 to 90 while it is on (the range they accept), 0 when it is off or deletes only files (auto_delete_scope "attachments"). Never set on direct messages. auto_delete_hours is the precise value (doc/timed-messages.md). |
auto_delete_follows_default | boolean | AutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off). |
auto_delete_hours | integer | AutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay. |
auto_delete_scope | string | AutoDeleteScope is what the period removes: "all" the messages with their files, "attachments" only the files. |
category_id (required) | string | null | |
created_at (required) | string (date-time) | |
id (required) | string (uuid) | |
is_lobby | boolean | IsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md). |
is_stage | boolean | IsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md). |
is_temp | boolean | IsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty. |
leader_id | string (uuid) | LeaderID is the leader of a temporary Talk: the member who may rename it and set its member limit. Absent on every other channel. |
name (required) | string | |
number (required) | integer | Number is the channel's short, stable link number (/c/12-general). |
previous_slugs | string[] | PreviousSlugs are the slugs the channel had before a rename, oldest first. Old links resolve through them; no other channel ever takes one. |
slow_mode_seconds (required) | integer | SlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt. |
slug | string | Slug is the channel's address in the web app (/c/general, /v/lounge): unique server-wide, lowercase ASCII. The id stays the key everywhere. |
sort_order (required) | integer | |
topic (required) | string | |
type (required) | ChannelType | |
user_limit (required) | integer | UserLimit is the most members a voice channel admits at once; 0 = no limit. |
Set a channel's auto-delete
PUT /api/admin/channels/{id}/auto-delete
A background sweeper removes what is older than the period: with scope "all" the messages with their attachments (broadcasting message_delete for each), with "attachments" only the files (the messages stay and show the files as removed; message_update for each). Pinned messages and their files stay, and so do thread roots that still have a newer or pinned reply. hours (0 to 8760) wins over the older days (0, 1, 7, 30, 90); 0 turns it off for this channel even when the community has a default; use_default makes the channel follow the community default. Conversations and their call Talks never take part (404). Requires the Manage channels permission. Changing the setting is written to the audit log (channel.auto_delete_set), and every sweep that removed something as channel.auto_delete_run with the counts. Needs the channels.auto_delete feature; hours, scope and use_default need channels.auto_delete.v2.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource ID. |
Request body (application/json, required): AutoDeleteRequest
| Field | Type | Description |
|---|---|---|
days | integer | Days is the older form: 1, 7, 30 or 90; 0 turns auto-delete off. Hours wins when both are given. |
hours | integer | null | Hours is the period in hours, 1 to 8760 (365 days); 0 turns it off for this channel, also when the community has a default. |
scope | string | Scope is what goes: "all" (the default) the messages with their files, "attachments" only the files. |
use_default | boolean | UseDefault makes the channel follow the community default; days and hours are then ignored. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated channel. | Channel |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs, days other than 0, 1, 7, 30, 90, hours outside 0 to 8760, an unknown scope, or none of hours, days and use_default. | 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 |
Channel
| Field | Type | Description |
|---|---|---|
auto_delete_days | integer | AutoDeleteDays is the effective auto-delete period in days for older clients: whole days rounded down and held within 1 to 90 while it is on (the range they accept), 0 when it is off or deletes only files (auto_delete_scope "attachments"). Never set on direct messages. auto_delete_hours is the precise value (doc/timed-messages.md). |
auto_delete_follows_default | boolean | AutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off). |
auto_delete_hours | integer | AutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay. |
auto_delete_scope | string | AutoDeleteScope is what the period removes: "all" the messages with their files, "attachments" only the files. |
category_id (required) | string | null | |
created_at (required) | string (date-time) | |
id (required) | string (uuid) | |
is_lobby | boolean | IsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md). |
is_stage | boolean | IsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md). |
is_temp | boolean | IsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty. |
leader_id | string (uuid) | LeaderID is the leader of a temporary Talk: the member who may rename it and set its member limit. Absent on every other channel. |
name (required) | string | |
number (required) | integer | Number is the channel's short, stable link number (/c/12-general). |
previous_slugs | string[] | PreviousSlugs are the slugs the channel had before a rename, oldest first. Old links resolve through them; no other channel ever takes one. |
slow_mode_seconds (required) | integer | SlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt. |
slug | string | Slug is the channel's address in the web app (/c/general, /v/lounge): unique server-wide, lowercase ASCII. The id stays the key everywhere. |
sort_order (required) | integer | |
topic (required) | string | |
type (required) | ChannelType | |
user_limit (required) | integer | UserLimit is the most members a voice channel admits at once; 0 = no limit. |
Preview a channel's auto-delete
POST /api/admin/channels/{id}/auto-delete/preview
A dry run of PUT /api/admin/channels/{id}/auto-delete with the same body: how many messages and files the setting would remove at its next run, and when that is. Changes nothing. Requires the Manage channels permission in the channel; the counts are of a channel the caller can already read. Needs the channels.auto_delete.v2 feature.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource ID. |
Request body (application/json, required): AutoDeleteRequest
| Field | Type | Description |
|---|---|---|
days | integer | Days is the older form: 1, 7, 30 or 90; 0 turns auto-delete off. Hours wins when both are given. |
hours | integer | null | Hours is the period in hours, 1 to 8760 (365 days); 0 turns it off for this channel, also when the community has a default. |
scope | string | Scope is what goes: "all" (the default) the messages with their files, "attachments" only the files. |
use_default | boolean | UseDefault makes the channel follow the community default; days and hours are then ignored. |
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: 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 |
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. |
Duplicate a channel
POST /api/admin/channels/{id}/duplicate
Creates a channel with the source's name (unchanged; names need not be unique), type, topic and category, placed directly below the source: the channels after it in its category (or among the uncategorized channels) move down by one. Its permission overwrites are copied, so a copy of a private channel stays private. Messages, reactions, read state and per-user notification levels are not copied. No request body. 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 |
|---|---|---|
| 201 | Created channel. | Channel |
| 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 |
Channel
| Field | Type | Description |
|---|---|---|
auto_delete_days | integer | AutoDeleteDays is the effective auto-delete period in days for older clients: whole days rounded down and held within 1 to 90 while it is on (the range they accept), 0 when it is off or deletes only files (auto_delete_scope "attachments"). Never set on direct messages. auto_delete_hours is the precise value (doc/timed-messages.md). |
auto_delete_follows_default | boolean | AutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off). |
auto_delete_hours | integer | AutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay. |
auto_delete_scope | string | AutoDeleteScope is what the period removes: "all" the messages with their files, "attachments" only the files. |
category_id (required) | string | null | |
created_at (required) | string (date-time) | |
id (required) | string (uuid) | |
is_lobby | boolean | IsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md). |
is_stage | boolean | IsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md). |
is_temp | boolean | IsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty. |
leader_id | string (uuid) | LeaderID is the leader of a temporary Talk: the member who may rename it and set its member limit. Absent on every other channel. |
name (required) | string | |
number (required) | integer | Number is the channel's short, stable link number (/c/12-general). |
previous_slugs | string[] | PreviousSlugs are the slugs the channel had before a rename, oldest first. Old links resolve through them; no other channel ever takes one. |
slow_mode_seconds (required) | integer | SlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt. |
slug | string | Slug is the channel's address in the web app (/c/general, /v/lounge): unique server-wide, lowercase ASCII. The id stays the key everywhere. |
sort_order (required) | integer | |
topic (required) | string | |
type (required) | ChannelType | |
user_limit (required) | integer | UserLimit is the most members a voice channel admits at once; 0 = no limit. |
Update a forum's settings
PATCH /api/channels/{channelID}/forum-settings
Changes the fields sent: whether posts need a tag, and the guidelines text (at most 1000 characters; empty clears it). Requires Manage channels.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): UpdateForumSettingsRequest
| Field | Type | Description |
|---|---|---|
guidelines | string | |
require_tag | boolean |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated settings. | ForumSettings |
| 400 | INVALID_INPUT | ErrorResponse |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
ForumSettings
| Field | Type | Description |
|---|---|---|
guidelines (required) | string | Guidelines is shown above the new-post form (plain text, at most 1000 characters). |
require_tag (required) | boolean | RequireTag: every post carries at least one tag (waived for a member who may apply none, so a forum without usable tags is not closed). |
Create a forum tag
POST /api/channels/{channelID}/tags
Adds a new tag at the end of the forum channel's tag order (up to 20). Requires Manage channels.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): CreateForumTagRequest
| Field | Type | Description |
|---|---|---|
color | string | Color is a palette name (gray, red, orange, yellow, green, teal, blue, purple, pink); omitted means none. |
emoji | string | |
moderated | boolean | Moderated: only members with Manage messages apply or remove the tag. |
name (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created tag. | ForumTag |
| 400 | INVALID_INPUT | ErrorResponse |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
| 409 | CONFLICT | ErrorResponse |
ForumTag
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | |
color | string | Color is a name from ForumTagColors, or empty for the plain look. |
created_at (required) | string (date-time) | |
emoji | string | |
id (required) | string (uuid) | |
moderated (required) | boolean | Moderated tags are applied and removed only by members with Manage messages. |
name (required) | string | |
position (required) | integer | Position is the tag's place in the forum's own order (1 is first). |
Reorder a forum's tags
PUT /api/channels/{channelID}/tags/order
Sets the order of the tags. The body names every tag of the forum exactly once. Requires Manage channels.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): ReorderForumTagsRequest
| Field | Type | Description |
|---|---|---|
tag_ids (required) | string (uuid)[] | TagIDs lists every tag of the forum once, in the new order. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The tags in their new order. | ForumTag[] |
| 400 | INVALID_INPUT | ErrorResponse |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
Delete a forum tag
DELETE /api/channels/{channelID}/tags/{tagID}
Removes a tag from the forum channel. Requires Manage channels.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
tagID | path | string (uuid) | yes | Tag ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
Update a forum tag
PATCH /api/channels/{channelID}/tags/{tagID}
Updates a tag's name, emoji, colour or moderated flag (only the fields sent change; an empty colour or emoji clears it). Requires Manage channels.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
tagID | path | string (uuid) | yes | Tag ID. |
Request body (application/json, required): UpdateForumTagRequest
| Field | Type | Description |
|---|---|---|
color | string | Color is a palette name; an empty string clears it. |
emoji | string | |
moderated | boolean | |
name | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated tag. | ForumTag |
| 400 | INVALID_INPUT | ErrorResponse |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
ForumTag
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | |
color | string | Color is a name from ForumTagColors, or empty for the plain look. |
created_at (required) | string (date-time) | |
emoji | string | |
id (required) | string (uuid) | |
moderated (required) | boolean | Moderated tags are applied and removed only by members with Manage messages. |
name (required) | string | |
position (required) | integer | Position is the tag's place in the forum's own order (1 is first). |