REST: Onboarding

The community's name, welcome text and rules, and a member's acceptance of them. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

Remove the community icon

DELETE /api/admin/community/icon

Owner and Administrators only; audited. Deletes the icon and its files; the Mnema icon shows again. Succeeds when there is none. Broadcasts community_updated.

Authentication: Session cookie

Responses

StatusMeaningBody
200Settings, without community_icon.Settings
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 change it, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Settings
FieldTypeDescription
community_iconstringCommunityIcon is the version of the community icon (GET /api/community/icon), empty while none is set. It changes with every upload. Set with PUT /api/admin/community/icon, not with the settings.
community_name (required)string
direct_messages_enabled (required)booleanDirectMessagesEnabled is the community's switch for direct messages (default on). Off: existing conversations stay readable and members can neither start new ones nor write in them.
rules_text (required)stringRulesText is Markdown. Empty means no rules: nothing is enforced.
rules_version (required)integerRulesVersion counts the published versions of the rules (0: never set). Members must have accepted it before they may post, react, upload or join a Talk (only while RulesText is not empty).
session_inactivity_days (required)integerSessionInactivityDays is how many days without an authenticated request sign a session out (1 to 365, default 7). Inactivity, not age.
start_channel_id (required)string | nullStartChannelID is the text channel new members land in; null for the first channel they can see.
welcome_text (required)stringWelcomeText is Markdown, shown to new members first.

Set the community icon

PUT /api/admin/community/icon

Owner and Administrators only; audited. multipart/form-data with an image in field 'icon' (PNG, JPEG, GIF or WebP, at most 5 MB, at least 128x128 pixels; SVG and animations are rejected). The server never stores the upload: it decodes it, crops the centre square and writes new 512x512 and 128x128 PNG files, so metadata such as EXIF is gone. Replaces the previous icon. Broadcasts community_updated.

Authentication: Session cookie

Request body (multipart/form-data, required): object

FieldTypeDescription
icon (required)string (binary)Image file, at most 5 MB.

Responses

StatusMeaningBody
200Settings, with the new community_icon version.Settings
400Invalid input (INVALID_INPUT): no file, too small or too large in pixels, animated, or the picture cannot be read.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 change it, or cross-origin request rejected.ErrorResponse
413PAYLOAD_TOO_LARGE: body or file exceeds the limit.ErrorResponse
415UNSUPPORTED_MEDIA_TYPE: the file type is not allowed.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available, or image processing is busy.ErrorResponse
Settings
FieldTypeDescription
community_iconstringCommunityIcon is the version of the community icon (GET /api/community/icon), empty while none is set. It changes with every upload. Set with PUT /api/admin/community/icon, not with the settings.
community_name (required)string
direct_messages_enabled (required)booleanDirectMessagesEnabled is the community's switch for direct messages (default on). Off: existing conversations stay readable and members can neither start new ones nor write in them.
rules_text (required)stringRulesText is Markdown. Empty means no rules: nothing is enforced.
rules_version (required)integerRulesVersion counts the published versions of the rules (0: never set). Members must have accepted it before they may post, react, upload or join a Talk (only while RulesText is not empty).
session_inactivity_days (required)integerSessionInactivityDays is how many days without an authenticated request sign a session out (1 to 365, default 7). Inactivity, not age.
start_channel_id (required)string | nullStartChannelID is the text channel new members land in; null for the first channel they can see.
welcome_text (required)stringWelcomeText is Markdown, shown to new members first.

Read the Owner's first-run checklist

GET /api/admin/first-run

Owner only. The steps (name the community, invite people, review the channels, set up voice, check the status, optionally roles and rules), each with whether it is done, whether the Owner closed the checklist and whether every required step is done. Steps tick themselves from real state; channels and status once the Owner has opened that page. A community that already had members before the checklist existed starts closed.

Authentication: Session cookie

Responses

StatusMeaningBody
200Checklist.FirstRun
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may read it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
FirstRun
FieldTypeDescription
complete (required)booleanComplete is true when every step that is not optional is done.
hidden (required)booleanHidden is true once the Owner closed the checklist (or when the community was already in use before the checklist existed). The server menu reopens it.
steps (required)FirstRunStep[]

Close, reopen or advance the Owner's first-run checklist

PUT /api/admin/first-run

Owner only. hidden closes or reopens the checklist; visited adds the steps the Owner has opened (channels, status). Returns the checklist as it now stands.

Authentication: Session cookie

Request body (application/json, required): FirstRunInput

FieldTypeDescription
hiddenboolean | nullHidden closes (true) or reopens (false) the checklist; left out, it stays as it is.
visitedstring[]Visited are steps the Owner has now opened: channels, status. They are added, never removed.

Responses

StatusMeaningBody
200Checklist.FirstRun
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: only the Owner may change it, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
FirstRun
FieldTypeDescription
complete (required)booleanComplete is true when every step that is not optional is done.
hidden (required)booleanHidden is true once the Owner closed the checklist (or when the community was already in use before the checklist existed). The server menu reopens it.
steps (required)FirstRunStep[]

Read the onboarding settings

GET /api/admin/onboarding

Owner and Administrators only.

Authentication: Session cookie

Responses

StatusMeaningBody
200Settings.Settings
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 read it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Settings
FieldTypeDescription
community_iconstringCommunityIcon is the version of the community icon (GET /api/community/icon), empty while none is set. It changes with every upload. Set with PUT /api/admin/community/icon, not with the settings.
community_name (required)string
direct_messages_enabled (required)booleanDirectMessagesEnabled is the community's switch for direct messages (default on). Off: existing conversations stay readable and members can neither start new ones nor write in them.
rules_text (required)stringRulesText is Markdown. Empty means no rules: nothing is enforced.
rules_version (required)integerRulesVersion counts the published versions of the rules (0: never set). Members must have accepted it before they may post, react, upload or join a Talk (only while RulesText is not empty).
session_inactivity_days (required)integerSessionInactivityDays is how many days without an authenticated request sign a session out (1 to 365, default 7). Inactivity, not age.
start_channel_id (required)string | nullStartChannelID is the text channel new members land in; null for the first channel they can see.
welcome_text (required)stringWelcomeText is Markdown, shown to new members first.

Set the onboarding settings

PUT /api/admin/onboarding

Owner and Administrators only; audited. Replaces the community name, welcome text, rules and start channel; direct_messages_enabled, when given, switches direct messages for the community on or off (existing conversations stay readable when off). Writing rules for the first time, or require_reacceptance, raises the rules version: members then have to accept again before they may post, react, upload or join a Talk (the Owner and bots are exempt). session_inactivity_days (1 to 365, default 7), when given, sets after how many days without an authenticated request a session is signed out. Empty rules enforce nothing. Broadcasts permissions_changed.

Authentication: Session cookie

Request body (application/json, required): SettingsInput

FieldTypeDescription
community_name (required)string
direct_messages_enabledboolean | nullDirectMessagesEnabled switches direct messages on or off for the community; left out, it stays as it is.
require_reacceptancebooleanRequireReacceptance raises the rules version, so every member (the Owner excepted) has to accept the rules again. The first time rules are written the version is raised on its own. Ignored while the rules are empty.
rules_text (required)string
session_inactivity_daysinteger | nullSessionInactivityDays sets the inactivity sign-out (1 to 365 days); left out, it stays as it is. It applies to running sessions at once.
start_channel_id (required)string | null
welcome_text (required)string

Responses

StatusMeaningBody
200Settings.Settings
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: only the Owner and members with the Administrator permission may change it, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Settings
FieldTypeDescription
community_iconstringCommunityIcon is the version of the community icon (GET /api/community/icon), empty while none is set. It changes with every upload. Set with PUT /api/admin/community/icon, not with the settings.
community_name (required)string
direct_messages_enabled (required)booleanDirectMessagesEnabled is the community's switch for direct messages (default on). Off: existing conversations stay readable and members can neither start new ones nor write in them.
rules_text (required)stringRulesText is Markdown. Empty means no rules: nothing is enforced.
rules_version (required)integerRulesVersion counts the published versions of the rules (0: never set). Members must have accepted it before they may post, react, upload or join a Talk (only while RulesText is not empty).
session_inactivity_days (required)integerSessionInactivityDays is how many days without an authenticated request sign a session out (1 to 365, default 7). Inactivity, not age.
start_channel_id (required)string | nullStartChannelID is the text channel new members land in; null for the first channel they can see.
welcome_text (required)stringWelcomeText is Markdown, shown to new members first.

Read the raid protection settings

GET /api/admin/raid

Owner and Administrators only. The sign-up throttle (at most join_limit new members within join_window_minutes), the minimum membership ages before a new member may write, react and speak (0: off), how many members joined within the window right now, and the state of the lockdown.

Authentication: Session cookie

Responses

StatusMeaningBody
200Settings.Settings
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 read it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Settings
FieldTypeDescription
join_limit (required)integerJoinLimit is the most new members within JoinWindowMinutes; 0: no throttle.
join_window_minutes (required)integer
joined_in_window (required)integerJoinedInWindow is how many members joined within the window right now.
lockdown (required)Lockdown
min_age_react_minutes (required)integer
min_age_speak_minutes (required)integer
min_age_write_minutes (required)integerMinAgeWriteMinutes, MinAgeReactMinutes and MinAgeSpeakMinutes are how long after joining a new member may write, react and speak; 0: at once.

Set the raid protection settings

PUT /api/admin/raid

Owner and Administrators only; audited. Replaces the sign-up throttle and the minimum membership ages. While the throttle is full, or a lockdown is on, new sign-ups answer UNAVAILABLE ("sign-ups are paused"); existing members are unaffected. A new member who has not reached an age yet cannot write, react or speak in Talks, start a conversation or write first in one, react in conversations (react wait) or join a conversation's call (speak wait); the answer is FORBIDDEN with the seconds left, and permissions carry new_member. Administrators, the Owner, bots and holders of Bypass new member limits never wait. Broadcasts permissions_changed.

Authentication: Session cookie

Request body (application/json, required): Input

FieldTypeDescription
join_limit (required)integer
join_window_minutes (required)integer
min_age_react_minutes (required)integer
min_age_speak_minutes (required)integer
min_age_write_minutes (required)integer

Responses

StatusMeaningBody
200Settings.Settings
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: only the Owner and members with the Administrator permission may change it, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Settings
FieldTypeDescription
join_limit (required)integerJoinLimit is the most new members within JoinWindowMinutes; 0: no throttle.
join_window_minutes (required)integer
joined_in_window (required)integerJoinedInWindow is how many members joined within the window right now.
lockdown (required)Lockdown
min_age_react_minutes (required)integer
min_age_speak_minutes (required)integer
min_age_write_minutes (required)integerMinAgeWriteMinutes, MinAgeReactMinutes and MinAgeSpeakMinutes are how long after joining a new member may write, react and speak; 0: at once.

Switch the lockdown on or off

PUT /api/admin/raid/lockdown

Owner and Administrators only; audited. While the lockdown is on, nobody new can sign up (also with a valid invite); with pause_invites no invite can be created either. hours ends it by itself after that long (1 to 720); without it, it stays until switched off. Existing members and their sessions are unaffected.

Authentication: Session cookie

Request body (application/json, required): LockdownInput

FieldTypeDescription
active (required)boolean
hoursintegerHours ends the lockdown by itself after this long (1 to 720); 0 or omitted: it stays until switched off.
pause_invitesboolean

Responses

StatusMeaningBody
200Settings.Settings
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: only the Owner and members with the Administrator permission may change it, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Settings
FieldTypeDescription
join_limit (required)integerJoinLimit is the most new members within JoinWindowMinutes; 0: no throttle.
join_window_minutes (required)integer
joined_in_window (required)integerJoinedInWindow is how many members joined within the window right now.
lockdown (required)Lockdown
min_age_react_minutes (required)integer
min_age_speak_minutes (required)integer
min_age_write_minutes (required)integerMinAgeWriteMinutes, MinAgeReactMinutes and MinAgeSpeakMinutes are how long after joining a new member may write, react and speak; 0: at once.

GET /api/admin/vanity-link

Owner and Administrators only.

Authentication: Session cookie

Responses

StatusMeaningBody
200Setting.VanitySettings
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 read it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
VanitySettings
FieldTypeDescription
accepts_signups (required)booleanAcceptsSignups: the link works as a permanent public invite.
pathstringPath is where the link lives on this server, empty without a slug; the web app puts its address in front.
slug (required)stringSlug is empty while there is no vanity link.

PUT /api/admin/vanity-link

Owner and Administrators only, except that only the Owner may turn accepts_signups on (or keep it on for a new name): an Administrator gets 403 FORBIDDEN; audited. slug is 3 to 32 characters (lowercase letters, digits, single hyphens inside; upper case is folded) and must not be a reserved word (400 INVALID_INPUT); an empty slug removes the link. The link is served at /join/{slug}. By default it only leads visitors to the sign-in page: sign-up stays invite-only. With accepts_signups it works as a permanent public invite (unlimited uses, no expiry), so anyone who knows it can register; leave it off to keep invites individual. One link per community; setting it replaces the previous one.

Authentication: Session cookie

Request body (application/json, required): VanityInput

FieldTypeDescription
accepts_signups (required)boolean
slug (required)stringSlug is 3 to 32 characters: lowercase letters, digits and single hyphens inside. Upper case is folded to lower. Empty removes the link.

Responses

StatusMeaningBody
200Setting.VanitySettings
400Invalid input (INVALID_INPUT): malformed JSON, or a slug of the wrong length or characters, or reserved.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 change it, only the Owner may turn accepts_signups on, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
VanitySettings
FieldTypeDescription
accepts_signups (required)booleanAcceptsSignups: the link works as a permanent public invite.
pathstringPath is where the link lives on this server, empty without a slug; the web app puts its address in front.
slug (required)stringSlug is empty while there is no vanity link.

Community icon

GET /api/community/icon

The icon the Owner set for the community, a square PNG. Public (no session): the community name next to it is public too, also on an invite-only server. size is 128 or 512 (default). 404 (NOT_FOUND) while no icon is set. The community_icon field of GET /api/health holds the current version; a request with v equal to it is cacheable for a year (immutable), any other is revalidated with ETag and Last-Modified after 5 minutes.

Authentication: none

Parameters

NameInTypeRequiredDescription
sizequeryintegernoEdge in pixels.
vquerystringnoVersion from GET /api/health (community_icon).

Responses

StatusMeaningBody
200PNG.string
304Not modified (If-None-Match, If-Modified-Since).
400Invalid input (INVALID_INPUT): size is not 128 or 512.ErrorResponse
404NOT_FOUND: no icon is set.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse

Read the onboarding state

GET /api/onboarding

The community's name, welcome text and rules, whether the caller still has to accept the rules, the start channel (if the caller can view it) and the caller's dismissed tips.

Authentication: Session cookie

Responses

StatusMeaningBody
200State.State
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
State
FieldTypeDescription
community_name (required)string
dismissed_tips (required)string[]DismissedTips are the tips the member closed.
rules_accepted_version (required)integerRulesAcceptedVersion is the version the member accepted last.
rules_pending (required)booleanRulesPending is true while the member has to accept the rules; until then posting, reacting, uploading and joining a Talk answer RULES_NOT_ACCEPTED. Never true for the Owner.
rules_text (required)string
rules_version (required)integerRulesVersion is the version in force; 0 while there are no rules.
start_channel_id (required)string | nullStartChannelID is the channel to open after the welcome flow; null when none is set or the member cannot view it.
welcome_done (required)booleanWelcomeDone is true once the member finished the welcome flow.
welcome_text (required)string

Accept the community rules

POST /api/onboarding/accept

Records that the caller accepted the rules in force. version must be the current rules version; if the rules changed meanwhile the answer is 409 and the client reloads them. Lifts the RULES_NOT_ACCEPTED restrictions at once, including in the WebSocket hub.

Authentication: Session cookie

Request body (application/json, required): AcceptInput

FieldTypeDescription
version (required)integerVersion is the rules version the member saw (State.RulesVersion).

Responses

StatusMeaningBody
204Accepted.
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
409CONFLICT: the rules changed; reload them.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Store dismissed tips

PUT /api/onboarding/tips

Adds tip ids to the caller's dismissed tips and optionally marks the welcome flow finished; returns the resulting state.

Authentication: Session cookie

Request body (application/json, required): TipsInput

FieldTypeDescription
dismissed_tipsstring[]DismissedTips are tip ids to add (at most 32 per call, 64 stored).
welcome_doneboolean | nullWelcomeDone marks the welcome flow finished.

Responses

StatusMeaningBody
200State.State
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
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
State
FieldTypeDescription
community_name (required)string
dismissed_tips (required)string[]DismissedTips are the tips the member closed.
rules_accepted_version (required)integerRulesAcceptedVersion is the version the member accepted last.
rules_pending (required)booleanRulesPending is true while the member has to accept the rules; until then posting, reacting, uploading and joining a Talk answer RULES_NOT_ACCEPTED. Never true for the Owner.
rules_text (required)string
rules_version (required)integerRulesVersion is the version in force; 0 while there are no rules.
start_channel_id (required)string | nullStartChannelID is the channel to open after the welcome flow; null when none is set or the member cannot view it.
welcome_done (required)booleanWelcomeDone is true once the member finished the welcome flow.
welcome_text (required)string

Something wrong on this page? Tell us.