REST:Â Moderation
Generated from mnema-talk v3.3.13 (cca4f0fdb723).
List automod rules
GET /api/admin/automod
The automod rules in the order they were made, and the end of the running raid restriction if there is one. Needs the Administrator permission (the Owner always). The rules check every new or edited message and every sign-up; see doc/moderation.md.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The rules. | AutomodList |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Administrator permission. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
AutomodList
| Field | Type | Description |
|---|---|---|
raid_until | string (date-time) | RaidUntil is set while raid protection is restricting newcomers. |
rules (required) | Rule[] |
Create an automod rule
POST /api/admin/automod/rules
Adds a rule: blocked words, link filter, mention spam, new-account protection or raid protection (only one). At most 25 rules. Needs the Administrator permission. Recorded in the audit log as automod.rule_create.
Authentication: Session cookie
Request body (application/json, required): RuleInput
| Field | Type | Description |
|---|---|---|
action (required) | string | |
config (required) | Settings | |
enabled (required) | boolean | |
exempt_channels | string (uuid)[] | |
exempt_roles | string (uuid)[] | |
kind (required) | string | |
name (required) | string | |
timeout_seconds | integer |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The rule. | Rule |
| 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: missing the Administrator permission. | ErrorResponse |
| 409 | CONFLICT: 25 rules exist, or raid protection exists already. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Rule
| Field | Type | Description |
|---|---|---|
action (required) | string | Action is what a hit does to the message; raid protection only flags. |
config (required) | Settings | |
enabled (required) | boolean | |
exempt_channels (required) | string (uuid)[] | |
exempt_roles (required) | string (uuid)[] | ExemptRoles and ExemptChannels are skipped by the rule. |
id (required) | string (uuid) | |
kind (required) | string | |
name (required) | string | |
timeout_seconds (required) | integer | TimeoutSeconds, when above 0, also times the author out for that long. |
updated_at (required) | string (date-time) |
Delete an automod rule
DELETE /api/admin/automod/rules/{id}
Removes a rule. The entries it already made in the moderation queue stay. Needs the Administrator permission. Recorded in the audit log as automod.rule_delete.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Rule ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | 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: missing the Administrator permission. | 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 |
Replace an automod rule
PUT /api/admin/automod/rules/{id}
Replaces every setting of a rule; its kind cannot change. Needs the Administrator permission. Recorded in the audit log as automod.rule_update.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Rule ID. |
Request body (application/json, required): RuleInput
| Field | Type | Description |
|---|---|---|
action (required) | string | |
config (required) | Settings | |
enabled (required) | boolean | |
exempt_channels | string (uuid)[] | |
exempt_roles | string (uuid)[] | |
kind (required) | string | |
name (required) | string | |
timeout_seconds | integer |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The rule. | Rule |
| 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: missing the Administrator permission. | 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 |
Rule
| Field | Type | Description |
|---|---|---|
action (required) | string | Action is what a hit does to the message; raid protection only flags. |
config (required) | Settings | |
enabled (required) | boolean | |
exempt_channels (required) | string (uuid)[] | |
exempt_roles (required) | string (uuid)[] | ExemptRoles and ExemptChannels are skipped by the rule. |
id (required) | string (uuid) | |
kind (required) | string | |
name (required) | string | |
timeout_seconds (required) | integer | TimeoutSeconds, when above 0, also times the author out for that long. |
updated_at (required) | string (date-time) |
List reports
GET /api/admin/reports
The moderation queue, newest first. Needs Manage reports (the Owner and Administrators always). The list holds no message text; open a report for that.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | no | Only reports with this status; all lists every status. |
before | query | string (uuid) | no | Page back: only reports older than this report. |
limit | query | integer | no | Page size, at most 100. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of reports. | ReportsPage |
| 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: missing the Manage reports permission. | ErrorResponse |
| 404 | NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ReportsPage
| Field | Type | Description |
|---|---|---|
has_more (required) | boolean | |
reports (required) | Report[] |
Count open reports
GET /api/admin/reports/open-count
How many reports are open, without the 100-entry cap of the list. Needs Manage reports (the Owner and Administrators always). The same number reaches the moderators' open sessions as the reports_open WebSocket event whenever a report is filed or closed.
Authentication: Session cookie
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The open count. | OpenCountResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage reports permission. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
OpenCountResponse
| Field | Type | Description |
|---|---|---|
open (required) | integer |
Delete a report
DELETE /api/admin/reports/{id}
Removes a closed report and the copy of the messages it kept. An open report cannot be deleted; close it first. Needs Manage reports. Recorded in the audit log as report.delete.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Report ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | 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: missing the Manage reports permission. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the report is still open. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Get a report
GET /api/admin/reports/{id}
The report with the copy of the reported message and up to 20 messages around it, as they were when it was filed. Needs Manage reports. This is the only way a moderator reads any part of a direct message.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Report ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The report. | ReportDetail |
| 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: missing the Manage reports permission. | 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 |
ReportDetail
| Field | Type | Description |
|---|---|---|
automod_outcome | string | AutomodOutcome says what the rule did: blocked the message, only flagged it, or raised a raid alert. |
automod_rule | string | AutomodRule names the rule of an automod entry, as it was when it hit. |
category (required) | string | |
channel_id | string (uuid) | ChannelID and ChannelName are left out for a direct message. |
channel_name | string | |
created_at (required) | string (date-time) | |
hit_count | integer | HitCount counts the hits merged into an automod entry (1 for a report). |
id (required) | string (uuid) | |
kind (required) | string | Kind is channel or dm for a reported message, alert for an automod alert that is about no message (a raid). |
message_id | string (uuid) | MessageID is left out for an automod entry about a blocked message (it was never stored) and for an alert. |
note (required) | string | Note is what the reporter wrote. |
reported | ReportParty | |
reporter | ReportParty | |
resolution_note | string | ResolutionNote is the moderator's note on closing the report. |
resolved_at | string (date-time) | |
resolved_by | ReportParty | |
snapshot (required) | ReportSnapshot | |
source | string | Source is member for a report a member filed, automod for an entry the automod rules made (no Reporter then). |
status (required) | string |
Close a report
POST /api/admin/reports/{id}/resolve
Marks an open report resolved or dismissed. The reporter is not notified. Needs Manage reports. Recorded in the audit log as report.resolve.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Report ID. |
Request body (application/json, required): ResolveReportRequest
| Field | Type | Description |
|---|---|---|
note | string | Note is kept with the report, up to 500 characters. |
status (required) | string | Status closes the report: resolved (acted on) or dismissed (no action). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The closed report. | Report |
| 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: missing the Manage reports permission. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the report is already closed. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Report
| Field | Type | Description |
|---|---|---|
automod_outcome | string | AutomodOutcome says what the rule did: blocked the message, only flagged it, or raised a raid alert. |
automod_rule | string | AutomodRule names the rule of an automod entry, as it was when it hit. |
category (required) | string | |
channel_id | string (uuid) | ChannelID and ChannelName are left out for a direct message. |
channel_name | string | |
created_at (required) | string (date-time) | |
hit_count | integer | HitCount counts the hits merged into an automod entry (1 for a report). |
id (required) | string (uuid) | |
kind (required) | string | Kind is channel or dm for a reported message, alert for an automod alert that is about no message (a raid). |
message_id | string (uuid) | MessageID is left out for an automod entry about a blocked message (it was never stored) and for an alert. |
note (required) | string | Note is what the reporter wrote. |
reported | ReportParty | |
reporter | ReportParty | |
resolution_note | string | ResolutionNote is the moderator's note on closing the report. |
resolved_at | string (date-time) | |
resolved_by | ReportParty | |
source | string | Source is member for a report a member filed, automod for an entry the automod rules made (no Reporter then). |
status (required) | string |
A member's moderation history
GET /api/admin/users/{id}/moderation
The timeline of what moderators and automod did about a member (timeouts, bans, kicks, role changes by moderators, reports about them, automod hits) and the private moderator notes about them. Needs Manage reports; the member themselves never gets it, not even with the permission. A report appears with its category and status only, never with its message text. The Owner and Administrators always pass.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The history. | History |
| 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: missing the Manage reports permission, or the member is yourself. | 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 |
History
| Field | Type | Description |
|---|---|---|
events (required) | HistoryEvent[] | Events is the timeline, newest first, at most the latest 200. |
notes (required) | Note[] | Notes are the private moderator notes, newest first. |
strikes (required) | integer | Strikes counts the notes marked as strikes. |
Add a moderator note
POST /api/admin/users/{id}/moderation/notes
Writes a private note about a member, optionally counted as a strike. Needs a highest role above the member's (never the Owner). Only moderators with Manage reports see it; the member never does, and it is not in their data export. At most 100 notes per member. Recorded in the audit log as moderation.note_add (without the text).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
Request body (application/json, required): NoteRequest
| Field | Type | Description |
|---|---|---|
body (required) | string | |
strike (required) | boolean |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The note. | Note |
| 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: missing the Manage reports permission, the member is yourself, the Owner, or not ranked below you. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the member already has 100 notes. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Note
| Field | Type | Description |
|---|---|---|
author_id (required) | string (uuid) | |
author_name (required) | string | |
body (required) | string | |
can_delete (required) | boolean | CanDelete: the caller wrote it, or is an Administrator. |
created_at (required) | string (date-time) | |
id (required) | string (uuid) | |
mine (required) | boolean | Mine: the caller wrote it and may edit and delete it. |
strike (required) | boolean | Strike counts the note in the member's strikes. |
updated_at (required) | string (date-time) |
Delete a moderator note
DELETE /api/admin/users/{id}/moderation/notes/{noteID}
Deletes a note you wrote; an Administrator (or the Owner) may delete any note. Needs Manage reports. Recorded in the audit log as moderation.note_delete.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
noteID | path | string (uuid) | yes | Note ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | 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: missing the Manage reports permission, or the note is another moderator's and you are no Administrator. | 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 |
Edit your moderator note
PUT /api/admin/users/{id}/moderation/notes/{noteID}
Changes the text or the strike flag of a note you wrote, while the member's highest role is still below yours. Nobody edits another moderator's note. Needs Manage reports. Recorded in the audit log as moderation.note_edit (without the text).
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | User ID. |
noteID | path | string (uuid) | yes | Note ID. |
Request body (application/json, required): NoteRequest
| Field | Type | Description |
|---|---|---|
body (required) | string | |
strike (required) | boolean |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The note. | Note |
| 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: missing the Manage reports permission, or the note is another moderator's. | 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 |
Note
| Field | Type | Description |
|---|---|---|
author_id (required) | string (uuid) | |
author_name (required) | string | |
body (required) | string | |
can_delete (required) | boolean | CanDelete: the caller wrote it, or is an Administrator. |
created_at (required) | string (date-time) | |
id (required) | string (uuid) | |
mine (required) | boolean | Mine: the caller wrote it and may edit and delete it. |
strike (required) | boolean | Strike counts the note in the member's strikes. |
updated_at (required) | string (date-time) |