REST: Users

Profiles, presence and members. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

List blocked members

GET /api/me/blocks

The members the caller has blocked, newest first. Blocking is private: the blocked member is never told, and nothing they can read depends on it. A blocked member's mentions and replies create no inbox entry, mention count or push for the caller; clients collapse their messages.

Authentication: Session cookie

Responses

StatusMeaningBody
200The caller's blocked members.BlockedMember[]
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

Unblock a member

DELETE /api/me/blocks/{userID}

Idempotent. Broadcasts block_updated to the caller's own sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
userIDpathstring (uuid)yesMember ID.

Responses

StatusMeaningBody
204Unblocked (or was not blocked).
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

Block a member

PUT /api/me/blocks/{userID}

Idempotent. At most 500 blocks per member. The blocked member is not told and cannot detect the block through this API; direct messages between the two members stop working with a generic error. Broadcasts block_updated to the caller's own sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
userIDpathstring (uuid)yesMember ID.

Responses

StatusMeaningBody
204Blocked (or already blocked).
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
409CONFLICT: the block list is full.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

List members

GET /api/members

Active accounts, the Owner first, then by display name, with voice_seconds (time in Talks @everyone can see) and message_count. Enabled bots are members too (is_bot, added_by) and hold the built-in Bot role; incoming-webhook authors are not listed. Disabled accounts remain available in the admin account list and historical messages. Presence and locale are not filled.

Authentication: Session cookie

Responses

StatusMeaningBody
200Members.Member[]
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

Turn off two-factor sign-in

POST /api/users/me/2fa/disable

Needs the current password and a current authenticator code or an unused recovery code. Deletes the secret and all recovery codes. 409 when two-factor sign-in is off.

Authentication: Session cookie

Request body (application/json, required): TwoFactorProofRequest

FieldTypeDescription
code (required)string
current_password (required)string (password)

Responses

StatusMeaningBody
204Two-factor sign-in is off.
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 password or the code is incorrect, or cross-origin request rejected.ErrorResponse
409CONFLICT: two-factor sign-in is not on.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Turn on two-factor sign-in

POST /api/users/me/2fa/enable

Confirms the first code of the pending secret from POST /api/users/me/2fa/setup, turns two-factor sign-in on and returns ten single-use recovery codes, once. From the next sign-in the password is followed by a code. Wrong codes count toward the account's second-factor lockout.

Authentication: Session cookie

Request body (application/json, required): TwoFactorEnableRequest

FieldTypeDescription
code (required)stringCode is the six digits the app shows for the new secret.

Responses

StatusMeaningBody
200Recovery codes, shown once.RecoveryCodes
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 code is incorrect, or cross-origin request rejected.ErrorResponse
409CONFLICT: two-factor sign-in is already on.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
RecoveryCodes
FieldTypeDescription
recovery_codes (required)string[]

Make new recovery codes

POST /api/users/me/2fa/recovery-codes

Needs the current password and a current authenticator code or an unused recovery code. Replaces all recovery codes with ten new single-use ones, shown once.

Authentication: Session cookie

Request body (application/json, required): TwoFactorProofRequest

FieldTypeDescription
code (required)string
current_password (required)string (password)

Responses

StatusMeaningBody
200Recovery codes, shown once.RecoveryCodes
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 password or the code is incorrect, or cross-origin request rejected.ErrorResponse
409CONFLICT: two-factor sign-in is not on.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
RecoveryCodes
FieldTypeDescription
recovery_codes (required)string[]

Start two-factor setup

POST /api/users/me/2fa/setup

Needs the current password. Creates a new pending authenticator secret (an earlier unconfirmed one is replaced) and returns it as text and as otpauth:// URI for the QR code. Nothing changes at sign-in until POST /api/users/me/2fa/enable confirms a code. 409 when two-factor sign-in is already on.

Authentication: Session cookie

Request body (application/json, required): TwoFactorSetupRequest

FieldTypeDescription
current_password (required)string (password)

Responses

StatusMeaningBody
200Pending secret.TwoFactorSetup
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 current password is incorrect, or cross-origin request rejected.ErrorResponse
409CONFLICT: two-factor sign-in is already on.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
TwoFactorSetup
FieldTypeDescription
otpauth_uri (required)stringOtpauthURI is the same secret as an otpauth:// URI, for the QR code.
secret (required)stringSecret is the shared secret in base32, for typing into an app by hand.

Own sign-in security

GET /api/users/me/account

The caller's e-mail address and whether it is confirmed, and whether the server can send mail. Visible to the account itself only.

Authentication: Session cookie

Responses

StatusMeaningBody
200Account security.AccountInfo
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
AccountInfo
FieldTypeDescription
confirmation_sentbooleanConfirmationSent is only present in the answer to PUT /api/users/me/email for a new address: false when the address was saved but the confirmation mail was refused (too many mails or SMTP failure), so the client can offer to send it again. Omitted when no mail was due.
emailstringEmail is the caller's own address; omitted when none is set. It is never shown to other members or administrators.
email_verified (required)booleanEmailVerified is true once the address was confirmed by its link.
mail_available (required)booleanMailAvailable is true when the server can send e-mail (SMTP is configured): addresses can be confirmed and passwords reset by mail.
recovery_codes_remaining (required)integerRecoveryCodesRemaining is how many single-use recovery codes are unused (0 when two-factor sign-in is off).
two_factor_enabled (required)booleanTwoFactorEnabled is true while sign-in asks for an authenticator code.

Remove avatar

DELETE /api/users/me/avatar

Deletes the avatar and its stored file. Succeeds when there is none. Needs the profile.avatar_remove feature. Broadcasts user_update.

Authentication: Session cookie

Responses

StatusMeaningBody
200Updated user, without avatar_url.User
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
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Upload avatar

POST /api/users/me/avatar

multipart/form-data with an image in field 'avatar' (PNG, JPEG, GIF or WebP, max 5 MB). The server never stores the upload: it crops the centre square, shrinks it to at most 512x512 (never enlarged) and writes a new file, so metadata such as EXIF (GPS, camera model) is gone. An animated GIF stays animated within a budget of 16 million pixels (canvas times frames, at most 100 frames); animated WebP is rejected. Replaces and deletes the previous avatar. Broadcasts user_update.

Authentication: Session cookie

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

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

Responses

StatusMeaningBody
200Updated user.User
400Invalid input (INVALID_INPUT): no file, too many frames, too large in pixels, or the picture cannot be read.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
413PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON).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
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Remove the profile banner

DELETE /api/users/me/banner

Deletes the banner and its stored file. Succeeds when there is none. Needs the profile.banner feature.

Authentication: Session cookie

Responses

StatusMeaningBody
200Updated user, without banner_url.User
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
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Set the profile banner

PUT /api/users/me/banner

multipart/form-data with an image in field 'banner' (PNG, JPEG, GIF or WebP, at most 5 MB, at least 300x100 pixels). The server never stores the upload: it decodes it, crops the centre 3:1, shrinks it to at most 1500x500 and writes a new file, so metadata such as EXIF is gone. An animated GIF stays animated within a budget of 16 million pixels (canvas times frames, at most 100 frames); animated WebP is rejected. Replaces and deletes the previous banner. Needs the profile.banner feature. Same rate limit as other uploads.

Authentication: Session cookie

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

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

Responses

StatusMeaningBody
200Updated user, including banner_url.User
400Invalid input (INVALID_INPUT): no file, too small or too large in pixels, too many frames, or the picture cannot be read.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
413PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON).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
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Delete my account

POST /api/users/me/delete

Erases the caller's personal data (GDPR Art. 17) and cannot be undone. Needs the current password and, while two-factor sign-in is on, a current code; wrong answers count toward the usual lockouts. The Owner account cannot be deleted (403). Profile, avatar, e-mail address, sessions, tokens, reactions, uploads (files too), invites, settings and roles are deleted. The account's messages stay readable as written by "Deleted member" but lose their text, link cards and pins, so threads keep their shape; replies and quotes by other members stay. Audit entries about the account lose names and details. The username becomes free. The request signs the caller out everywhere.

Authentication: Session cookie

Request body (application/json, required): DeleteAccountRequest

FieldTypeDescription
codestringCode is a current authenticator code or an unused recovery code; needed only while two-factor sign-in is on.
current_password (required)string (password)

Responses

StatusMeaningBody
204Account deleted.
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: wrong password or code, the Owner account, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: the server is busy (the erasure kept meeting other writes of the account and was rolled back); nothing was deleted, try again shortly.ErrorResponse

Set the account's e-mail address

PUT /api/users/me/email

Optional; used only to confirm the address and to reset the password. Needs the current password and, while two-factor sign-in is on, a current code. A new address starts unconfirmed; when the server can send mail, a single-use link (valid 24 hours) is sent to it. Typing the confirmed address again keeps it confirmed. The address is saved even when the mail is refused (too many mails for this account or address in the last hour, or the mail server fails); the answer then has confirmation_sent false and POST /api/users/me/email/resend sends it again. Never shown to other members. Wrong passwords count toward the same lockout as PUT /api/auth/password.

Authentication: Session cookie

Request body (application/json, required): SetEmailRequest

FieldTypeDescription
codestringCode is a current authenticator code or an unused recovery code; needed only while two-factor sign-in is on.
current_password (required)string (password)
email (required)string (email)

Responses

StatusMeaningBody
200Account security after the change.AccountInfo
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 current password or code is incorrect, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
AccountInfo
FieldTypeDescription
confirmation_sentbooleanConfirmationSent is only present in the answer to PUT /api/users/me/email for a new address: false when the address was saved but the confirmation mail was refused (too many mails or SMTP failure), so the client can offer to send it again. Omitted when no mail was due.
emailstringEmail is the caller's own address; omitted when none is set. It is never shown to other members or administrators.
email_verified (required)booleanEmailVerified is true once the address was confirmed by its link.
mail_available (required)booleanMailAvailable is true when the server can send e-mail (SMTP is configured): addresses can be confirmed and passwords reset by mail.
recovery_codes_remaining (required)integerRecoveryCodesRemaining is how many single-use recovery codes are unused (0 when two-factor sign-in is off).
two_factor_enabled (required)booleanTwoFactorEnabled is true while sign-in asks for an authenticator code.

Remove the account's e-mail address

POST /api/users/me/email/remove

Always possible; needs the current password and, while two-factor sign-in is on, a current code. Pending confirmation and reset links stop working. Without an address, password reset by e-mail is not available for the account.

Authentication: Session cookie

Request body (application/json, required): PasswordConfirmRequest

FieldTypeDescription
codestringCode is a current authenticator code or an unused recovery code; needed only while two-factor sign-in is on.
current_password (required)string (password)

Responses

StatusMeaningBody
200Account security after the change.AccountInfo
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 current password or code is incorrect, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests, or the second step is locked.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
AccountInfo
FieldTypeDescription
confirmation_sentbooleanConfirmationSent is only present in the answer to PUT /api/users/me/email for a new address: false when the address was saved but the confirmation mail was refused (too many mails or SMTP failure), so the client can offer to send it again. Omitted when no mail was due.
emailstringEmail is the caller's own address; omitted when none is set. It is never shown to other members or administrators.
email_verified (required)booleanEmailVerified is true once the address was confirmed by its link.
mail_available (required)booleanMailAvailable is true when the server can send e-mail (SMTP is configured): addresses can be confirmed and passwords reset by mail.
recovery_codes_remaining (required)integerRecoveryCodesRemaining is how many single-use recovery codes are unused (0 when two-factor sign-in is off).
two_factor_enabled (required)booleanTwoFactorEnabled is true while sign-in asks for an authenticator code.

Send the confirmation mail again

POST /api/users/me/email/resend

For an address that is set but not confirmed, when the server can send mail. At most one per minute and five per hour for the account; an earlier link stops working.

Authentication: Session cookie

Responses

StatusMeaningBody
204Mail sent.
400Invalid input (INVALID_INPUT): no unconfirmed address, or the server cannot send mail.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
503UNAVAILABLE: the mail could not be sent.ErrorResponse

Status of my data export

GET /api/users/me/export

The caller's newest export: none, pending, ready (with the time it stops being downloadable), failed, downloaded or expired, and when a new one may be requested. After a complete download the export stays ready for one more hour (never past its expiry) with downloaded_at set, then reads downloaded.

Authentication: Session cookie

Responses

StatusMeaningBody
200Export status.ExportStatus
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
ExportStatus
FieldTypeDescription
downloaded_atstring (date-time)DownloadedAt is when the export was first downloaded completely.
expires_atstring (date-time)ExpiresAt is when a ready export stops being downloadable (after a download, the end of the hour in which it can be downloaded again).
next_request_atstring (date-time)NextRequestAt is when a new export may be requested; omitted if now.
requested_atstring (date-time)
size_bytes (required)integer
state (required)stringState is none, pending, ready, failed, downloaded or expired.

Request an export of my data

POST /api/users/me/export

GDPR Art. 20: builds a ZIP of JSON files with the caller's own data (profile, settings, roles, own messages with the channel names the caller can still see, reactions, upload list with links, audit entries about the account without other people's names). Needs the current password and, while two-factor sign-in is on, a current code. One export per 24 hours; it is built in the background (poll GET /api/users/me/export), can be downloaded within 24 hours and is deleted one hour after the first complete download. Needs object storage. Size-bounded; nothing of other members' personal data is included.

Authentication: Session cookie

Request body (application/json, required): ExportRequest

FieldTypeDescription
codestringCode is a current authenticator or recovery code; needed only while two-factor sign-in is on.
current_password (required)string (password)

Responses

StatusMeaningBody
202Accepted; the export is being built.ExportStatus
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: wrong password or code, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: an export was already requested in the last 24 hours, or too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: object storage is not available, every export slot is busy, or the server is shutting down; no export was started and none counts toward the daily limit.ErrorResponse
ExportStatus
FieldTypeDescription
downloaded_atstring (date-time)DownloadedAt is when the export was first downloaded completely.
expires_atstring (date-time)ExpiresAt is when a ready export stops being downloadable (after a download, the end of the hour in which it can be downloaded again).
next_request_atstring (date-time)NextRequestAt is when a new export may be requested; omitted if now.
requested_atstring (date-time)
size_bytes (required)integer
state (required)stringState is none, pending, ready, failed, downloaded or expired.

Download my data export

GET /api/users/me/export/download

The finished ZIP with its Content-Length. An interrupted download leaves the export as it was; after the first complete download the file can be downloaded again for one hour (never past its expiry) and is then deleted, so a copy the client lost after the server sent it is not gone. Refuses requests that browsers mark as coming from another site (Sec-Fetch-Site) and prefetches (Sec-Purpose or Purpose: prefetch). 404 when there is no ready export, it expired or its hour after the download is over.

Authentication: Session cookie

Responses

StatusMeaningBody
200The ZIP archive.file
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the request came from another site (Sec-Fetch-Site is neither same-origin nor none), or it is a prefetch.ErrorResponse
404NOT_FOUND: no export is ready, it expired, or the hour after its download is over.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Set UI language

PUT /api/users/me/locale

Stores the language (en or de) on the account, so every device of the member shows the same one.

Authentication: Session cookie

Request body (application/json, required): SetLocaleRequest

FieldTypeDescription
locale (required)string

Responses

StatusMeaningBody
200Updated user.User
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
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Choose presence

PUT /api/users/me/presence

Applies to the user's live WebSocket status.

Authentication: Session cookie

Request body (application/json, required): SetPresenceRequest

FieldTypeDescription
presence (required)stringPresence is the chosen presence; "offline" is never chosen, it follows from having no open WebSocket.

Responses

StatusMeaningBody
200Updated user.User
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
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Read the privacy settings

GET /api/users/me/privacy

Who may start direct messages with the caller.

Authentication: Session cookie

Responses

StatusMeaningBody
200The settings.Privacy
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
Privacy
FieldTypeDescription
dm_policy (required)stringDMPolicy is everyone (the default) or nobody. It only decides who can start a conversation with the caller or add them to a group; existing conversations go on.

Set the privacy settings

PUT /api/users/me/privacy

Sets who may start direct messages with the caller: everyone or nobody.

Authentication: Session cookie

Request body (application/json, required): Privacy

FieldTypeDescription
dm_policy (required)stringDMPolicy is everyone (the default) or nobody. It only decides who can start a conversation with the caller or add them to a group; existing conversations go on.

Responses

StatusMeaningBody
200The settings.Privacy
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
Privacy
FieldTypeDescription
dm_policy (required)stringDMPolicy is everyone (the default) or nobody. It only decides who can start a conversation with the caller or add them to a group; existing conversations go on.

Update display name and bio

PUT /api/users/me/profile

Broadcasts user_update.

Authentication: Session cookie

Request body (application/json, required): UpdateProfileRequest

FieldTypeDescription
biostring
display_namestringDisplayName: empty resets it to the username.

Responses

StatusMeaningBody
200Updated user.User
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
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Set own status line

PUT /api/users/me/status

Broadcasts user_update. With expires_at the status clears itself at that time (the server then broadcasts user_update again).

Authentication: Session cookie

Request body (application/json, required): SetStatusRequest

FieldTypeDescription
expires_atstring (date-time)ExpiresAt makes the status clear itself at this absolute time (the client computes it from the member's time zone). Omitted or null: it stays until changed. Must lie in the future, at most a year ahead; ignored when the status is cleared and when an admin sets another member's status.
status_text (required)stringStatusText: empty clears the status.

Responses

StatusMeaningBody
200Updated user.User
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
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Get a user profile

GET /api/users/{userID}

Includes voice_seconds (time in Talks @everyone can see, the part others may see), message_count and the banner_url of the profile banner. Other users are returned without the private presence choice.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
userIDpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
200The user.User
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
User
FieldTypeDescription
avatar_urlstringAvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none.
banner_urlstringBannerURL is the API URL of the profile banner (/api/media/{id}); omitted when none and in every payload but the profile endpoints (GET /api/users/{userID}, GET /api/auth/me and the banner routes).
bio (required)string
created_at (required)string (date-time)
display_name (required)string
id (required)string (uuid)
locale (required)stringLocale is the chosen UI language ("de", "en"); empty until chosen.
message_countinteger
presencestringPresence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub.
role (required)stringRole is "admin" for the Owner (the one account named by ADMIN_USERNAME, all-powerful and untouchable) and "user" for everybody else; what a user may do beyond the defaults comes from roles (see GET /api/permissions).
rules_pendingbooleanRulesPending is true while the caller has to accept the community rules (POST /api/onboarding/accept) before posting, reacting, uploading or joining a Talk. Only set in responses about the caller's own account.
status_expires_atstring (date-time)StatusExpiresAt is when the status line clears itself; omitted when it stays until changed.
status_text (required)stringStatusText is a free-text status line; empty when unset.
username (required)string
voice_secondsintegerActivity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent.

Something wrong on this page? Tell us.