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
| Status | Meaning | Body |
|---|---|---|
| 200 | The caller's blocked members. | BlockedMember[] |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userID | path | string (uuid) | yes | Member ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Unblocked (or was not blocked). | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userID | path | string (uuid) | yes | Member ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Blocked (or already blocked). | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the block list is full. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Status | Meaning | Body |
|---|---|---|
| 200 | Members. | Member[] |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Field | Type | Description |
|---|---|---|
code (required) | string | |
current_password (required) | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Two-factor sign-in is off. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the password or the code is incorrect, or cross-origin request rejected. | ErrorResponse |
| 409 | CONFLICT: two-factor sign-in is not on. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_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
| Field | Type | Description |
|---|---|---|
code (required) | string | Code is the six digits the app shows for the new secret. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Recovery codes, shown once. | RecoveryCodes |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the code is incorrect, or cross-origin request rejected. | ErrorResponse |
| 409 | CONFLICT: two-factor sign-in is already on. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
RecoveryCodes
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
code (required) | string | |
current_password (required) | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Recovery codes, shown once. | RecoveryCodes |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the password or the code is incorrect, or cross-origin request rejected. | ErrorResponse |
| 409 | CONFLICT: two-factor sign-in is not on. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
RecoveryCodes
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
current_password (required) | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Pending secret. | TwoFactorSetup |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the current password is incorrect, or cross-origin request rejected. | ErrorResponse |
| 409 | CONFLICT: two-factor sign-in is already on. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
TwoFactorSetup
| Field | Type | Description |
|---|---|---|
otpauth_uri (required) | string | OtpauthURI is the same secret as an otpauth:// URI, for the QR code. |
secret (required) | string | Secret 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Account security. | AccountInfo |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
AccountInfo
| Field | Type | Description |
|---|---|---|
confirmation_sent | boolean | ConfirmationSent 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. |
email | string | Email is the caller's own address; omitted when none is set. It is never shown to other members or administrators. |
email_verified (required) | boolean | EmailVerified is true once the address was confirmed by its link. |
mail_available (required) | boolean | MailAvailable 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) | integer | RecoveryCodesRemaining is how many single-use recovery codes are unused (0 when two-factor sign-in is off). |
two_factor_enabled (required) | boolean | TwoFactorEnabled 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user, without avatar_url. | User |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Field | Type | Description |
|---|---|---|
avatar (required) | string (binary) | Image file, at most 5 MB. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user. | User |
| 400 | Invalid input (INVALID_INPUT): no file, too many frames, too large in pixels, or the picture cannot be read. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON). | ErrorResponse |
| 415 | UNSUPPORTED_MEDIA_TYPE: the file type is not allowed. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available, or image processing is busy. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user, without banner_url. | User |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Field | Type | Description |
|---|---|---|
banner (required) | string (binary) | Image file, at most 5 MB. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user, including banner_url. | User |
| 400 | Invalid input (INVALID_INPUT): no file, too small or too large in pixels, too many frames, or the picture cannot be read. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 413 | PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON). | ErrorResponse |
| 415 | UNSUPPORTED_MEDIA_TYPE: the file type is not allowed. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: a dependency (database, file storage) is not available, or image processing is busy. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Field | Type | Description |
|---|---|---|
code | string | Code 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
| Status | Meaning | Body |
|---|---|---|
| 204 | Account deleted. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: wrong password or code, the Owner account, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: 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
| Field | Type | Description |
|---|---|---|
code | string | Code 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Account security after the change. | AccountInfo |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the current password or code is incorrect, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
AccountInfo
| Field | Type | Description |
|---|---|---|
confirmation_sent | boolean | ConfirmationSent 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. |
email | string | Email is the caller's own address; omitted when none is set. It is never shown to other members or administrators. |
email_verified (required) | boolean | EmailVerified is true once the address was confirmed by its link. |
mail_available (required) | boolean | MailAvailable 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) | integer | RecoveryCodesRemaining is how many single-use recovery codes are unused (0 when two-factor sign-in is off). |
two_factor_enabled (required) | boolean | TwoFactorEnabled 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
| Field | Type | Description |
|---|---|---|
code | string | Code 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Account security after the change. | AccountInfo |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the current password or code is incorrect, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or the second step is locked. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
AccountInfo
| Field | Type | Description |
|---|---|---|
confirmation_sent | boolean | ConfirmationSent 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. |
email | string | Email is the caller's own address; omitted when none is set. It is never shown to other members or administrators. |
email_verified (required) | boolean | EmailVerified is true once the address was confirmed by its link. |
mail_available (required) | boolean | MailAvailable 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) | integer | RecoveryCodesRemaining is how many single-use recovery codes are unused (0 when two-factor sign-in is off). |
two_factor_enabled (required) | boolean | TwoFactorEnabled 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
| Status | Meaning | Body |
|---|---|---|
| 204 | Mail sent. | |
| 400 | Invalid input (INVALID_INPUT): no unconfirmed address, or the server cannot send mail. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Export status. | ExportStatus |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ExportStatus
| Field | Type | Description |
|---|---|---|
downloaded_at | string (date-time) | DownloadedAt is when the export was first downloaded completely. |
expires_at | string (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_at | string (date-time) | NextRequestAt is when a new export may be requested; omitted if now. |
requested_at | string (date-time) | |
size_bytes (required) | integer | |
state (required) | string | State 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
| Field | Type | Description |
|---|---|---|
code | string | Code is a current authenticator or recovery code; needed only while two-factor sign-in is on. |
current_password (required) | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 202 | Accepted; the export is being built. | ExportStatus |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: wrong password or code, or cross-origin request rejected. | ErrorResponse |
| 429 | RATE_LIMITED: an export was already requested in the last 24 hours, or too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
| 503 | UNAVAILABLE: 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
| Field | Type | Description |
|---|---|---|
downloaded_at | string (date-time) | DownloadedAt is when the export was first downloaded completely. |
expires_at | string (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_at | string (date-time) | NextRequestAt is when a new export may be requested; omitted if now. |
requested_at | string (date-time) | |
size_bytes (required) | integer | |
state (required) | string | State 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The ZIP archive. | file |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the request came from another site (Sec-Fetch-Site is neither same-origin nor none), or it is a prefetch. | ErrorResponse |
| 404 | NOT_FOUND: no export is ready, it expired, or the hour after its download is over. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Field | Type | Description |
|---|---|---|
locale (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user. | User |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Field | Type | Description |
|---|---|---|
presence (required) | string | Presence is the chosen presence; "offline" is never chosen, it follows from having no open WebSocket. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user. | User |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | Privacy |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Privacy
| Field | Type | Description |
|---|---|---|
dm_policy (required) | string | DMPolicy 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
| Field | Type | Description |
|---|---|---|
dm_policy (required) | string | DMPolicy 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | Privacy |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Privacy
| Field | Type | Description |
|---|---|---|
dm_policy (required) | string | DMPolicy 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
| Field | Type | Description |
|---|---|---|
bio | string | |
display_name | string | DisplayName: empty resets it to the username. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user. | User |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Field | Type | Description |
|---|---|---|
expires_at | string (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) | string | StatusText: empty clears the status. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated user. | User |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: cross-origin request rejected by the CSRF check. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userID | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The user. | User |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
User
| Field | Type | Description |
|---|---|---|
avatar_url | string | AvatarURL is the API URL of the avatar (/api/media/{id}); omitted when none. |
banner_url | string | BannerURL 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) | string | Locale is the chosen UI language ("de", "en"); empty until chosen. |
message_count | integer | |
presence | string | Presence is the chosen presence, only present in responses about the caller's own account; others see the live one from the hub. |
role (required) | string | Role 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_pending | boolean | RulesPending 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_at | string (date-time) | StatusExpiresAt is when the status line clears itself; omitted when it stays until changed. |
status_text (required) | string | StatusText is a free-text status line; empty when unset. |
username (required) | string | |
voice_seconds | integer | Activity totals, filled where they are shown (members, profiles): time spent in voice rooms @everyone can see (finished stays) and messages sent. |