REST: Roles

Roles, member roles, permission lists and channel or category overwrites (Manage roles or Manage channels). Generated from mnema-talk v3.3.13 (cca4f0fdb723).

Permission overwrites of a category

GET /api/admin/categories/{id}/overwrites

The allow/deny pairs set directly on the category. Its channels inherit them. Needs the Manage channels permission and view access.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesCategory ID.

Responses

StatusMeaningBody
200Overwrites.OverwritesBody
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage channels permission.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
OverwritesBody
FieldTypeDescription
overwrites (required)Overwrite[]

Replace the permission overwrites of a category

PUT /api/admin/categories/{id}/overwrites

Replaces all overwrites of the category. Only channel permissions can be overwritten; the caller can only allow what they hold themselves; the Owner cannot be the subject of one. Everyone affected is told to refresh and removed from Talks they may no longer join.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesCategory ID.

Request body (application/json, required): OverwritesBody

FieldTypeDescription
overwrites (required)Overwrite[]

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage channels permission, the subject is the Owner, or allowing a permission you lack, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Permission overwrites of a channel

GET /api/admin/channels/{id}/overwrites

The allow/deny pairs set directly on the channel. A channel also inherits its category's (its own win). Needs the Manage channels permission and view access.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200Overwrites.OverwritesBody
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage channels permission.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
OverwritesBody
FieldTypeDescription
overwrites (required)Overwrite[]

Replace the permission overwrites of a channel

PUT /api/admin/channels/{id}/overwrites

Replaces all overwrites of the channel. Only channel permissions can be overwritten; the caller can only allow what they hold themselves; the Owner cannot be the subject of one. Everyone affected is told to refresh and removed from Talks they may no longer join.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesChannel ID.

Request body (application/json, required): OverwritesBody

FieldTypeDescription
overwrites (required)Overwrite[]

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage channels permission, the subject is the Owner, or allowing a permission you lack, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Create a role

POST /api/admin/roles

The new role sits at the bottom of the hierarchy, just above @everyone. Needs the Manage roles permission and the caller cannot grant permissions they lack. Broadcasts roles_changed.

Authentication: Session cookie

Request body (application/json, required): RoleInput

FieldTypeDescription
colorinteger
descriptionstringDescription is one line shown to members choosing roles.
hoistboolean
max_upload_mbinteger | nullMaxUploadMB: absent leaves it alone, null inherits the global limit, a number sets the role's limit. Only the Owner may send it.
mentionableboolean
namestring
permissionsinteger
self_assignablebooleanSelfAssignable lets members add and remove the role themselves; refused for @everyone, managed roles and roles with Administrator or admin-area permissions.

Responses

StatusMeaningBody
201Created role.Role
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage roles permission, or granting a permission you lack, or cross-origin request rejected.ErrorResponse
409CONFLICT: too many roles.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Role
FieldTypeDescription
bot_user_idstring (uuid)BotUserID is set on a bot's own managed role: the account of the one bot that holds it. The role is named after the bot and goes with it.
color (required)integer
descriptionstringDescription says in a line what the role is for; the member picker shows it.
hoist (required)boolean
id (required)string (uuid)
is_everyone (required)boolean
managedbooleanManaged marks a role the server maintains: the shared Bot role (every bot holds it) and each bot's own role (BotUserID). Only bots hold them; they cannot be renamed by hand, removed from a bot or deleted.
max_upload_mb (required)integer | nullMaxUploadMB overrides the upload limit of this role's members; null inherits the global limit. A member gets the highest override of their roles (@everyone included), never above the server's ceiling.
mentionable (required)boolean
name (required)string
permissions (required)integer
position (required)integer
self_assignablebooleanSelfAssignable lets every member add or remove this role on their own account. Only roles without Administrator or admin-area permissions can be flagged, never @everyone or a managed role. Omitted when false.

Reorder roles

PUT /api/admin/roles/order

Sets the hierarchy. The caller can only move roles below their own highest role, to places below it. Broadcasts roles_changed.

Authentication: Session cookie

Request body (application/json, required): ReorderRequest

FieldTypeDescription
role_ids (required)string (uuid)[]RoleIDs lists every custom role (not @everyone) exactly once, highest first.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage roles permission, or moving roles at or above your highest role, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Delete a role

DELETE /api/admin/roles/{id}

Removes it from everyone who has it and from all overwrites. Only roles below the caller's highest role. @everyone cannot be deleted. Broadcasts roles_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesRole ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage roles permission, or the role is not below your highest role, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Edit a role

PATCH /api/admin/roles/{id}

Omitted fields are kept. Only roles below the caller's highest role can be edited, and only permissions the caller holds can be added or removed. @everyone only has its permissions editable. Members who hold the role are told to refresh (permissions_changed) and removed from Talks they may no longer join. Broadcasts roles_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesRole ID.

Request body (application/json, required): RoleInput

FieldTypeDescription
colorinteger
descriptionstringDescription is one line shown to members choosing roles.
hoistboolean
max_upload_mbinteger | nullMaxUploadMB: absent leaves it alone, null inherits the global limit, a number sets the role's limit. Only the Owner may send it.
mentionableboolean
namestring
permissionsinteger
self_assignablebooleanSelfAssignable lets members add and remove the role themselves; refused for @everyone, managed roles and roles with Administrator or admin-area permissions.

Responses

StatusMeaningBody
200Updated role.Role
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage roles permission, the role is not below your highest role, or granting a permission you lack, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Role
FieldTypeDescription
bot_user_idstring (uuid)BotUserID is set on a bot's own managed role: the account of the one bot that holds it. The role is named after the bot and goes with it.
color (required)integer
descriptionstringDescription says in a line what the role is for; the member picker shows it.
hoist (required)boolean
id (required)string (uuid)
is_everyone (required)boolean
managedbooleanManaged marks a role the server maintains: the shared Bot role (every bot holds it) and each bot's own role (BotUserID). Only bots hold them; they cannot be renamed by hand, removed from a bot or deleted.
max_upload_mb (required)integer | nullMaxUploadMB overrides the upload limit of this role's members; null inherits the global limit. A member gets the highest override of their roles (@everyone included), never above the server's ceiling.
mentionable (required)boolean
name (required)string
permissions (required)integer
position (required)integer
self_assignablebooleanSelfAssignable lets every member add or remove this role on their own account. Only roles without Administrator or admin-area permissions can be flagged, never @everyone or a managed role. Omitted when false.

View the server as a role

GET /api/admin/roles/{id}/view-as

A read-only preview of the sidebar for a made-up member who holds only @everyone and this role: the categories and channels that member can see, Talks marked can_join, and the channel permissions they hold in each channel, computed by the real permission engine (overwrites included). It never shows more than the caller can see themselves: a channel the caller cannot view is left out whatever the role could see. Needs Manage roles. Nobody is impersonated and nothing changes.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesRole ID (@everyone included).

Responses

StatusMeaningBody
200Preview.ViewAsRole
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage roles permission.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ViewAsRole
FieldTypeDescription
administrator (required)booleanAdministrator is true when the role carries Administrator: such a member sees everything the caller sees and ignores channel overwrites.
categories (required)ViewAsCategory[]
role_id (required)string (uuid)
role_name (required)string
uncategorized (required)ViewAsChannel[]

Read the global upload limit

GET /api/admin/upload-limit

Owner only. The effective global limit, the operator's ceiling (MAX_UPLOAD_SIZE_MB) and whether uploaded pictures lose their metadata (strip_image_metadata).

Authentication: Session cookie

Responses

StatusMeaningBody
200Upload limit.UploadSettings
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
UploadSettings
FieldTypeDescription
ceiling_mb (required)integerCeilingMB is the operator's hard ceiling (MAX_UPLOAD_SIZE_MB).
max_upload_mb (required)integerMaxUploadMB is the effective global limit.
strip_image_metadatabooleanStripImageMetadata says whether the server removes metadata (EXIF with the GPS position, XMP, IPTC, comments, thumbnails) and anything that follows the picture from uploaded JPEG, PNG and WebP attachments (default on). A server that does not send it is older and keeps the metadata.

Set the global upload limit

PUT /api/admin/upload-limit

Owner only. Capped by the operator's ceiling (MAX_UPLOAD_SIZE_MB); null returns to the ceiling. Roles may override it per role. strip_image_metadata, when given, switches the removal of metadata (EXIF with the GPS position, XMP, IPTC, comments) from JPEG, PNG and WebP attachments on or off; it applies to uploads from then on. Broadcasts permissions_changed so clients refetch their effective limit.

Authentication: Session cookie

Request body (application/json, required): UploadLimitInput

FieldTypeDescription
max_upload_mb (required)integer | nullMaxUploadMB is the new global limit; null returns to the server's ceiling.
strip_image_metadataboolean | nullStripImageMetadata switches the removal of metadata from uploaded pictures on or off; left out, it stays as it is.

Responses

StatusMeaningBody
200Upload limit.UploadSettings
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: only the Owner may do this, or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
UploadSettings
FieldTypeDescription
ceiling_mb (required)integerCeilingMB is the operator's hard ceiling (MAX_UPLOAD_SIZE_MB).
max_upload_mb (required)integerMaxUploadMB is the effective global limit.
strip_image_metadatabooleanStripImageMetadata says whether the server removes metadata (EXIF with the GPS position, XMP, IPTC, comments, thumbnails) and anything that follows the picture from uploaded JPEG, PNG and WebP attachments (default on). A server that does not send it is older and keeps the metadata.

Set a member's roles

PUT /api/admin/users/{id}/roles

Replaces the member's custom roles. Only roles below the caller's highest role can be added or removed, and only on members whose highest role is below it. The Owner's roles cannot be changed (403). The member is told to refresh and removed from Talks they may no longer join. Broadcasts roles_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json, required): MemberRolesRequest

FieldTypeDescription
role_ids (required)string (uuid)[]RoleIDs are all custom roles the member should have.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage roles permission, the member is the Owner or not below you, or a role is not below your highest role, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Drop a self-assignable role

DELETE /api/me/roles/{id}

Removes the role from the caller's own account. Only roles listed by GET /api/roles/self-assignable; dropping a role the caller does not hold changes nothing. Recorded in the audit log as role.self_remove. Broadcasts member_roles_changed (the member's id and roles) and tells the caller to refresh (permissions_changed).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesRole ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the role is not open to self-assignment, or the caller is the Owner, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Take a self-assignable role

PUT /api/me/roles/{id}

Adds the role to the caller's own account. Only roles listed by GET /api/roles/self-assignable; asking for a role the caller already holds changes nothing. Recorded in the audit log as role.self_assign. Broadcasts member_roles_changed (the member's id and roles) and tells the caller to refresh (permissions_changed).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesRole ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the role is not open to self-assignment, or the caller is the Owner, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Own permissions

GET /api/permissions

The caller's server-wide permissions and, per viewable channel, what they may do there. Refetch after a permissions_changed event.

Authentication: Session cookie

Responses

StatusMeaningBody
200Permissions.PermissionsInfo
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
PermissionsInfo
FieldTypeDescription
can_start_direct_messagesboolean
catalog (required)Info[]Catalog lists every permission bit.
channels (required)ChannelPermissions[]Channels lists every channel the caller may view with what they may do there (bits).
direct_messages_enabledbooleanDirectMessagesEnabled is the community's switch for direct messages; CanStartDirectMessages says whether the caller may start them and write in them now (the switch is on, they hold Send direct messages, and no timeout or pending rules apply).
max_upload_mb (required)integerMaxUploadMB is the largest file the caller may upload, in MB: their roles' override or the global limit, never above the server's ceiling. It changes with permissions_changed.
new_memberNewMemberInfoNewMember is set while the caller is too new to write, react or speak (raid protection): per action the moment it opens up.
owner (required)booleanOwner is true for the Owner, who may do everything and cannot be restricted.
permissions (required)integerPermissions are the server-wide permissions (bits, see catalog).
role_ids (required)string (uuid)[]RoleIDs are the caller's custom roles, highest first.
rules_pendingbooleanRulesPending is set while the caller has to accept the community rules (POST /api/onboarding/accept); posting, reacting, uploading and joining a Talk answer RULES_NOT_ACCEPTED until then.
timeout_reasonstring
timeout_untilstring (date-time)TimeoutUntil and TimeoutReason are set while the caller is timed out: they can read but not post, react, speak or join Talks. The reason is the moderator's, and the caller's own to see.
top_position (required)integerTopPosition is the position of the caller's highest role (0 without one); the Owner is above every position. A member can only manage roles and members below it.

List roles

GET /api/roles

Every role, highest first; @everyone (is_everyone) is last. Roles are visible to all members, they colour names.

Authentication: Session cookie

Responses

StatusMeaningBody
200Roles.Role[]
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

List the roles members can choose

GET /api/roles/self-assignable

The roles an admin opened to self-assignment, highest first: ordinary roles without Administrator or admin-area permissions. Any member may read it; PUT and DELETE /api/me/roles/{id} take and drop them.

Authentication: Session cookie

Responses

StatusMeaningBody
200Roles members may choose for themselves.Role[]
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

Something wrong on this page? Tell us.