REST: Channels

Channel hierarchy and read state. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

Set category notification level

PUT /api/categories/{id}/notifications

The level channels of the category inherit when they have no setting of their own. A category the caller may not see answers 404 like a missing one. Notifies the user's other sessions with a read_state refresh.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesCategory ID.

Request body (application/json, required): SetNotifyLevelRequest

FieldTypeDescription
level (required)NotifyLevel
muted_untilstring | nullMutedUntil ends a mute (level mute only): in the future, at most a year ahead. Null or omitted mutes until unmuted.

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: cross-origin request rejected by the CSRF check.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

List categories and channels

GET /api/channels

Only the channels the caller may view; a category shows when its own permissions allow it or any of its channels is visible.

Authentication: Session cookie

Responses

StatusMeaningBody
200Channel hierarchy.ChannelHierarchy
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ChannelHierarchy
FieldTypeDescription
categories (required)Category[]
uncategorized (required)Channel[]

First unread message of a channel

GET /api/channels/{channelID}/first-unread

Returns the oldest top-level message by another member posted after since (the read marker the client saw when it opened the channel), so the client can jump to it when it is older than the loaded page. One indexed lookup; it changes nothing.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
sincequerystring (date-time)yesRFC 3339 time: the last-read time of the channel.

Responses

StatusMeaningBody
200OKFirstUnreadResponse
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
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
FirstUnreadResponse
FieldTypeDescription
message_id (required)string | nullMessageID is the oldest top-level message by someone else after since; null when there is none.

Get a forum's settings

GET /api/channels/{channelID}/forum-settings

Whether posts need a tag and the guidelines shown above the new-post form. Requires View channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200Settings.ForumSettings
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).

Set channel notification level

PUT /api/channels/{channelID}/notifications

Level all, mentions, mute or inherit (follow the category). A mute may end at muted_until (future, at most a year ahead). Notifies the user's other sessions with a read_state refresh.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): SetNotifyLevelRequest

FieldTypeDescription
level (required)NotifyLevel
muted_untilstring | nullMutedUntil ends a mute (level mute only): in the future, at most a year ahead. Null or omitted mutes until unmuted.

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: cross-origin request rejected by the CSRF check.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

List forum posts

GET /api/channels/{channelID}/posts

Root posts in a forum channel, ordered by latest activity or creation. Supports tag filtering, text search and pagination. Pinned posts come first and only on the first page (no before); the pages behind it hold unpinned posts. Requires View channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
sortquerystringnoSort order: 'latest_activity' (default; 'activity' is accepted as an alias) or 'newest' ('creation' is accepted as an alias). Other values are rejected.
tag_idquerystring (uuid)noFilter by tag ID.
qquerystringnoKeep posts whose title, first message or a reply contains this text (at most 100 characters).
limitqueryintegernoPage size.
beforequerystring (uuid)noPosts older than this post.
before_activityquerystring (date-time)noWith latest_activity order and before: the last_activity_at the client saw for the before post. Paging then continues exactly behind that position even when the post has got or lost a reply since.

Responses

StatusMeaningBody
200Posts.Message[]
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUND: the channel, or the before post (deleted since the previous page), does not exist.ErrorResponse
429RATE_LIMITED: too many requests, or the search (q) took too long.ErrorResponse

List a forum's unread posts

GET /api/channels/{channelID}/posts/unread

The posts (up to 200, newest activity first) with a post or reply of someone else the caller has not read since they last opened the post. Requires View channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200Unread posts.UnreadForumPosts
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
UnreadForumPosts
FieldTypeDescription
post_ids (required)string (uuid)[]

Mark a forum post read

PUT /api/channels/{channelID}/posts/{messageID}/read

Sets the caller's read marker of the post to now and returns the marker it had, which is where the first unread reply starts. Never moves backwards. Requires View channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesPost ID.

Responses

StatusMeaningBody
200The marker before.PostRead
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
PostRead
FieldTypeDescription
previous_read_at (required)string (date-time)PreviousReadAt is the read marker before this call (the day the caller joined for a post never opened). Replies of others after it are unread.

Mark a channel read

POST /api/channels/{channelID}/read

Moves the read marker forward to the given message, or to now when the body is omitted. Never moves backwards. Text and voice channels. Notifies the user's other sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json): MarkReadRequest

FieldTypeDescription
message_idstring | nullMessageID is the message to mark read up to; null or omitted means now.

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: cross-origin request rejected by the CSRF check.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

List forum tags

GET /api/channels/{channelID}/tags

The tags of a forum channel in the forum's own order. Requires View channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200Tags.ForumTag[]
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse

Mark unread from a message

POST /api/channels/{channelID}/unread

Sets the marker just before the message so it and everything after it counts as unread.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): MarkUnreadRequest

FieldTypeDescription
message_id (required)string (uuid)

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: cross-origin request rejected by the CSRF check.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Disconnect a member from a Talk

POST /api/channels/{id}/voice/{userID}/disconnect

Needs View channel and Disconnect members in this Talk: granted server-wide by a role, it works in every Talk; granted or denied by a role or member overwrite on the Talk or its category, only there. Members whose highest role is not below the caller's cannot be targeted, and the Owner cannot be removed (400). 400 also when the member is not in this Talk. Recorded in the audit log as voice.disconnect, read only by auditors who can view the Talk; a removal from a conversation's call Talk is not recorded.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesTalk ID.
userIDpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): bad IDs, or the member is not in this Talk.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Disconnect members permission in this Talk, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the Talk or the user does not exist, or the Talk is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Start a Talk from a direct message conversation

POST /api/dms/{id}/talk

Opens a temporary Talk that belongs to the conversation (no Create-a-Talk lobby is needed): only the conversation's members can see or join it, the Owner included, and it is removed when it is empty. The caller leads it. An invitation card is posted into the conversation and the other members are rung (dm_call_ring). The caller joins the Talk like any other (WebSocket voice_join). Counts against the caller's limit of 5 new Talks per 10 minutes (429). Broadcasts channels_changed and message_create.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesConversation ID.

Responses

StatusMeaningBody
201The new Talk and the invitation.StartTalkResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the caller cannot send in this conversation (not a member, blocked), or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the conversation does not exist or the caller is not in it.ErrorResponse
429RATE_LIMITED: too many requests, or too many new Talks.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
StartTalkResponse
FieldTypeDescription
channel_id (required)string (uuid)ChannelID is the new temporary Talk; the caller joins it like any Talk.
message (required)MessageMessage is the invitation card posted into the conversation.

Notification settings

GET /api/notification-settings

The caller's stored channel and category settings (level all, mentions or mute, with muted_until for timed mutes), plus the server-wide default under server. Channels and categories without a setting, and expired mutes, are not listed; the read-state array carries the effective level per channel. Only channels and categories the caller may view.

Authentication: Session cookie

Responses

StatusMeaningBody
200Stored settings.NotificationSettings
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
NotificationSettings
FieldTypeDescription
categories (required)CategoryNotifySetting[]
channels (required)ChannelNotifySetting[]
server (required)ServerNotifyServer is the member's server-wide default (always present).

Set server notification default

PUT /api/notification-settings/server

The caller's server-wide default: level all, mentions or mute (optionally until muted_until) and whether @all and @here are ignored. Channels and categories without a setting of their own follow it (channel, then category, then this default); conversations are not affected by the level. Notifies the user's other sessions with a read_state refresh.

Authentication: Session cookie

Request body (application/json, required): SetServerNotifyRequest

FieldTypeDescription
level (required)NotifyLevel
muted_untilstring | nullMutedUntil ends a mute (level mute only): in the future, at most a year ahead. Null or omitted mutes until unmuted.
suppress_everyonebooleanSuppressEveryone ignores @all and @here for the caller, at every level.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: cross-origin request rejected by the CSRF check.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Unread summary of all channels

GET /api/read-state

One entry per channel: unread messages and mentions since the last read, the time of the last read and the effective notification level. Drives the unread badges in the channel list.

Authentication: Session cookie

Responses

StatusMeaningBody
200One entry per channel (text channels and voice channels' chats).ReadState[]
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Mark everything read

POST /api/read-state/read-all

Moves the read marker of every channel the caller may view (or of one category's channels) to now; never backwards. Sends one read_state refresh to the user's sessions.

Authentication: Session cookie

Request body (application/json): MarkAllReadRequest

FieldTypeDescription
category_idstring | nullCategoryID limits the call to one category's channels; omitted or null means every channel the caller may view.

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
404NOT_FOUND: the category does not exist or the caller may not see it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Rename a temporary Talk or set its member limit

PATCH /api/talks/{id}

Only the leader of a temporary Talk (opened from a Create-a-Talk lobby) may change it, and only its name and member limit; the Manage channels permission is not needed. A leader is the member who opened the Talk, and after they leave the member who has been in it longest. 403 for anyone else, 404 when the Talk is not a temporary Talk the caller can see. Broadcasts channels_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesResource ID.

Request body (application/json, required): UpdateTalkRequest

FieldTypeDescription
namestring
user_limitintegerUserLimit caps the members of the Talk at once; 0 removes the limit.

Responses

StatusMeaningBody
200Updated Talk.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: the caller does not lead this Talk, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the Talk does not exist, is not a temporary Talk, or the caller cannot see it.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.

Invite a conversation to a Talk

POST /api/talks/{id}/invites

Posts an invitation card for the Talk into a direct message conversation of the caller ("Bring into Talk"). The caller needs to see and join the Talk and to send in the conversation. The card grants nothing: members who click Join go through the normal permission checks, and a member who cannot join the Talk sees that. Broadcasts message_create.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesTalk ID.

Request body (application/json, required): InviteToTalkRequest

FieldTypeDescription
conversation_id (required)string (uuid)ConversationID is the direct message conversation to post the card into.

Responses

StatusMeaningBody
201The invitation message.Message
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: the caller cannot join the Talk or send in the conversation, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the Talk or the conversation does not exist, or the caller cannot see it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Something wrong on this page? Tell us.