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

StatusMeaningBody
200The rules.AutomodList
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Administrator permission.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
AutomodList
FieldTypeDescription
raid_untilstring (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

FieldTypeDescription
action (required)string
config (required)Settings
enabled (required)boolean
exempt_channelsstring (uuid)[]
exempt_rolesstring (uuid)[]
kind (required)string
name (required)string
timeout_secondsinteger

Responses

StatusMeaningBody
201The rule.Rule
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 Administrator permission.ErrorResponse
409CONFLICT: 25 rules exist, or raid protection exists already.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Rule
FieldTypeDescription
action (required)stringAction 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)integerTimeoutSeconds, 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

NameInTypeRequiredDescription
idpathstring (uuid)yesRule ID.

Responses

StatusMeaningBody
204Deleted.
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 Administrator 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

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

NameInTypeRequiredDescription
idpathstring (uuid)yesRule ID.

Request body (application/json, required): RuleInput

FieldTypeDescription
action (required)string
config (required)Settings
enabled (required)boolean
exempt_channelsstring (uuid)[]
exempt_rolesstring (uuid)[]
kind (required)string
name (required)string
timeout_secondsinteger

Responses

StatusMeaningBody
200The rule.Rule
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 Administrator 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
Rule
FieldTypeDescription
action (required)stringAction 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)integerTimeoutSeconds, 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

NameInTypeRequiredDescription
statusquerystringnoOnly reports with this status; all lists every status.
beforequerystring (uuid)noPage back: only reports older than this report.
limitqueryintegernoPage size, at most 100.

Responses

StatusMeaningBody
200One page of reports.ReportsPage
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 reports permission.ErrorResponse
404NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ReportsPage
FieldTypeDescription
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

StatusMeaningBody
200The open count.OpenCountResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage reports permission.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
OpenCountResponse
FieldTypeDescription
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

NameInTypeRequiredDescription
idpathstring (uuid)yesReport ID.

Responses

StatusMeaningBody
204Deleted.
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 reports permission.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the report is still open.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_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

NameInTypeRequiredDescription
idpathstring (uuid)yesReport ID.

Responses

StatusMeaningBody
200The report.ReportDetail
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 reports 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
ReportDetail
FieldTypeDescription
automod_outcomestringAutomodOutcome says what the rule did: blocked the message, only flagged it, or raised a raid alert.
automod_rulestringAutomodRule names the rule of an automod entry, as it was when it hit.
category (required)string
channel_idstring (uuid)ChannelID and ChannelName are left out for a direct message.
channel_namestring
created_at (required)string (date-time)
hit_countintegerHitCount counts the hits merged into an automod entry (1 for a report).
id (required)string (uuid)
kind (required)stringKind is channel or dm for a reported message, alert for an automod alert that is about no message (a raid).
message_idstring (uuid)MessageID is left out for an automod entry about a blocked message (it was never stored) and for an alert.
note (required)stringNote is what the reporter wrote.
reportedReportParty
reporterReportParty
resolution_notestringResolutionNote is the moderator's note on closing the report.
resolved_atstring (date-time)
resolved_byReportParty
snapshot (required)ReportSnapshot
sourcestringSource 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

NameInTypeRequiredDescription
idpathstring (uuid)yesReport ID.

Request body (application/json, required): ResolveReportRequest

FieldTypeDescription
notestringNote is kept with the report, up to 500 characters.
status (required)stringStatus closes the report: resolved (acted on) or dismissed (no action).

Responses

StatusMeaningBody
200The closed report.Report
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 reports permission.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the report is already closed.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Report
FieldTypeDescription
automod_outcomestringAutomodOutcome says what the rule did: blocked the message, only flagged it, or raised a raid alert.
automod_rulestringAutomodRule names the rule of an automod entry, as it was when it hit.
category (required)string
channel_idstring (uuid)ChannelID and ChannelName are left out for a direct message.
channel_namestring
created_at (required)string (date-time)
hit_countintegerHitCount counts the hits merged into an automod entry (1 for a report).
id (required)string (uuid)
kind (required)stringKind is channel or dm for a reported message, alert for an automod alert that is about no message (a raid).
message_idstring (uuid)MessageID is left out for an automod entry about a blocked message (it was never stored) and for an alert.
note (required)stringNote is what the reporter wrote.
reportedReportParty
reporterReportParty
resolution_notestringResolutionNote is the moderator's note on closing the report.
resolved_atstring (date-time)
resolved_byReportParty
sourcestringSource 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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
200The history.History
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 reports permission, or the member is yourself.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
History
FieldTypeDescription
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)integerStrikes 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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.

Request body (application/json, required): NoteRequest

FieldTypeDescription
body (required)string
strike (required)boolean

Responses

StatusMeaningBody
201The note.Note
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 reports permission, the member is yourself, the Owner, or not ranked below you.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the member already has 100 notes.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Note
FieldTypeDescription
author_id (required)string (uuid)
author_name (required)string
body (required)string
can_delete (required)booleanCanDelete: the caller wrote it, or is an Administrator.
created_at (required)string (date-time)
id (required)string (uuid)
mine (required)booleanMine: the caller wrote it and may edit and delete it.
strike (required)booleanStrike 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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.
noteIDpathstring (uuid)yesNote ID.

Responses

StatusMeaningBody
204Deleted.
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 reports permission, or the note is another moderator's and you are no Administrator.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 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

NameInTypeRequiredDescription
idpathstring (uuid)yesUser ID.
noteIDpathstring (uuid)yesNote ID.

Request body (application/json, required): NoteRequest

FieldTypeDescription
body (required)string
strike (required)boolean

Responses

StatusMeaningBody
200The note.Note
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 reports permission, or the note is another moderator's.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Note
FieldTypeDescription
author_id (required)string (uuid)
author_name (required)string
body (required)string
can_delete (required)booleanCanDelete: the caller wrote it, or is an Administrator.
created_at (required)string (date-time)
id (required)string (uuid)
mine (required)booleanMine: the caller wrote it and may edit and delete it.
strike (required)booleanStrike counts the note in the member's strikes.
updated_at (required)string (date-time)

Something wrong on this page? Tell us.