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

FieldTypeDescription
category_idstring | null
is_stagebooleanIsStage creates the Talk as a Stage (voice channels only).
name (required)string
sort_orderinteger
topicstring
typeChannelType

Responses

StatusMeaningBody
201Created channel.Channel
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
Channel
FieldTypeDescription
auto_delete_daysintegerAutoDeleteDays 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_defaultbooleanAutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off).
auto_delete_hoursintegerAutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay.
auto_delete_scopestringAutoDeleteScope 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_lobbybooleanIsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md).
is_stagebooleanIsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md).
is_tempbooleanIsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty.
leader_idstring (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)integerNumber is the channel's short, stable link number (/c/12-general).
previous_slugsstring[]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)integerSlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt.
slugstringSlug 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)integerUserLimit 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

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, 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 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

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Request body (application/json, required): UpdateChannelRequest

FieldTypeDescription
is_lobbybooleanIsLobby 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_stagebooleanIsStage 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).
namestring
slow_mode_secondsintegerSlowModeSeconds 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.
topicstring
user_limitintegerUserLimit caps a voice channel's members at once; 0 removes the limit.

Responses

StatusMeaningBody
200Updated channel.Channel
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
Channel
FieldTypeDescription
auto_delete_daysintegerAutoDeleteDays 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_defaultbooleanAutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off).
auto_delete_hoursintegerAutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay.
auto_delete_scopestringAutoDeleteScope 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_lobbybooleanIsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md).
is_stagebooleanIsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md).
is_tempbooleanIsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty.
leader_idstring (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)integerNumber is the channel's short, stable link number (/c/12-general).
previous_slugsstring[]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)integerSlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt.
slugstringSlug 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)integerUserLimit 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

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Request body (application/json, required): AutoDeleteRequest

FieldTypeDescription
daysintegerDays is the older form: 1, 7, 30 or 90; 0 turns auto-delete off. Hours wins when both are given.
hoursinteger | nullHours is the period in hours, 1 to 8760 (365 days); 0 turns it off for this channel, also when the community has a default.
scopestringScope is what goes: "all" (the default) the messages with their files, "attachments" only the files.
use_defaultbooleanUseDefault makes the channel follow the community default; days and hours are then ignored.

Responses

StatusMeaningBody
200Updated channel.Channel
400Invalid 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
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
Channel
FieldTypeDescription
auto_delete_daysintegerAutoDeleteDays 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_defaultbooleanAutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off).
auto_delete_hoursintegerAutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay.
auto_delete_scopestringAutoDeleteScope 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_lobbybooleanIsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md).
is_stagebooleanIsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md).
is_tempbooleanIsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty.
leader_idstring (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)integerNumber is the channel's short, stable link number (/c/12-general).
previous_slugsstring[]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)integerSlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt.
slugstringSlug 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)integerUserLimit 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

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Request body (application/json, required): AutoDeleteRequest

FieldTypeDescription
daysintegerDays is the older form: 1, 7, 30 or 90; 0 turns auto-delete off. Hours wins when both are given.
hoursinteger | nullHours is the period in hours, 1 to 8760 (365 days); 0 turns it off for this channel, also when the community has a default.
scopestringScope is what goes: "all" (the default) the messages with their files, "attachments" only the files.
use_defaultbooleanUseDefault makes the channel follow the community default; days and hours are then ignored.

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

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

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Responses

StatusMeaningBody
201Created channel.Channel
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
Channel
FieldTypeDescription
auto_delete_daysintegerAutoDeleteDays 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_defaultbooleanAutoDeleteFollowsDefault says the channel has no setting of its own and follows the community default (which may be off).
auto_delete_hoursintegerAutoDeleteHours is the effective period after which messages (or, with the scope "attachments", their files) are removed; 0 = off. Pinned messages stay.
auto_delete_scopestringAutoDeleteScope 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_lobbybooleanIsLobby marks a Talk as a "Create a Talk" lobby: joining it opens a temporary Talk instead of taking a seat (doc/talks.md).
is_stagebooleanIsStage marks a Talk as a Stage: without talk power nobody speaks or shares video there (doc/talks.md).
is_tempbooleanIsTemp marks a temporary Talk opened from a lobby; it is removed again once it stays empty.
leader_idstring (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)integerNumber is the channel's short, stable link number (/c/12-general).
previous_slugsstring[]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)integerSlowModeSeconds is the least time between two messages of one member in this channel; 0 = off. Members who may manage messages here are exempt.
slugstringSlug 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)integerUserLimit 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): UpdateForumSettingsRequest

FieldTypeDescription
guidelinesstring
require_tagboolean

Responses

StatusMeaningBody
200Updated settings.ForumSettings
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
ForumSettings
FieldTypeDescription
guidelines (required)stringGuidelines is shown above the new-post form (plain text, at most 1000 characters).
require_tag (required)booleanRequireTag: 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): CreateForumTagRequest

FieldTypeDescription
colorstringColor is a palette name (gray, red, orange, yellow, green, teal, blue, purple, pink); omitted means none.
emojistring
moderatedbooleanModerated: only members with Manage messages apply or remove the tag.
name (required)string

Responses

StatusMeaningBody
201Created tag.ForumTag
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
409CONFLICTErrorResponse
ForumTag
FieldTypeDescription
channel_id (required)string (uuid)
colorstringColor is a name from ForumTagColors, or empty for the plain look.
created_at (required)string (date-time)
emojistring
id (required)string (uuid)
moderated (required)booleanModerated tags are applied and removed only by members with Manage messages.
name (required)string
position (required)integerPosition 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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): ReorderForumTagsRequest

FieldTypeDescription
tag_ids (required)string (uuid)[]TagIDs lists every tag of the forum once, in the new order.

Responses

StatusMeaningBody
200The tags in their new order.ForumTag[]
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse

Delete a forum tag

DELETE /api/channels/{channelID}/tags/{tagID}

Removes a tag from the forum channel. Requires Manage channels.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
tagIDpathstring (uuid)yesTag ID.

Responses

StatusMeaningBody
204Success, no content.
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse

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

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
tagIDpathstring (uuid)yesTag ID.

Request body (application/json, required): UpdateForumTagRequest

FieldTypeDescription
colorstringColor is a palette name; an empty string clears it.
emojistring
moderatedboolean
namestring

Responses

StatusMeaningBody
200Updated tag.ForumTag
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
ForumTag
FieldTypeDescription
channel_id (required)string (uuid)
colorstringColor is a name from ForumTagColors, or empty for the plain look.
created_at (required)string (date-time)
emojistring
id (required)string (uuid)
moderated (required)booleanModerated tags are applied and removed only by members with Manage messages.
name (required)string
position (required)integerPosition is the tag's place in the forum's own order (1 is first).

Something wrong on this page? Tell us.