ModerationController

struct ModerationController : APIRouteCollection

The collection of /api/v3/mod/ route endpoints and handler functions related to moderation tasks.

All routes in this group should be restricted to users with moderation priviliges. This controller returns data of a privileged nature, including contents of user reports, edit histories of user content, and log data about moderation actions.

Note that some moderation actions aren’t in this file. Most such endpoints have a handler method allowing a user to operate on their own content, but also allowing a mod to operate on other users’ content. For example, twarrtUpdateHandler lets a user edit a twarrt they wrote, but also lets mods edit any user’s twarrt.

The routes in this controller that return data on various Reportable content types are designed to return everything a Mod might need to make moderation decisions, all in one call. In many cases that means calls return multiple array types with no paging or array limits. In non-degenerate cases the arrays should less than ~20 elements. Additionally, there are few moderators and they won’t be calling these methods multiple times per second.

Show on GitHub

tokenAuthGroup Handlers (logged in)

  • reportsHandler(_:) Asynchronous

    GET /api/v3/mod/reports

    Retrieves the full Report model of all reports.

    Throws

    403 error if the user is not an admin.

    Declaration

    Swift

    func reportsHandler(_ req: Request) async throws -> [ReportModerationData]

    Return Value

    An array of Report objects

    Show on GitHub

  • POST /api/v3/mod/reports/ID/handleall

    This call is how a Moderator can take a user Report off the queue and begin handling it. More correctly, it takes all user reports referring to the same piece of content and marks them all handled at once.

    Moving reports through the ‘handling’ state is not necessary–you can go straight to ‘closed’–but this marks the reports as being ‘taken’ by the given mod so other mods can avoid duplicate or conflicting work. Also, any ModeratorActions taken while a mod has reports in the ‘handling’ state get tagged with an identifier that matches the actions to the reports. Reports should be closed once a mod is done with them.

    Throws

    403 error if the user is not an admin.

    Declaration

    Swift

    func beginProcessingReportsHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    reportID

    in URL path. Note that this method actually operates on all reports referring to the same content as the indicated report.

    Return Value

    200 OK on success

    Show on GitHub

  • POST /api/v3/mod/reports/ID/closeall

    Closes all reports filed against the same piece of content as the given report. That is, if there are several user reports concerning the same post, this will close all of them.

    Throws

    403 error if the user is not an admin.

    Declaration

    Swift

    func closeReportsHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    reportID

    in URL path. Note that this method actually operates on all reports referring to the same content as the indicated report.

    Return Value

    200 OK on success

    Show on GitHub

  • GET /api/v3/mod/moderationlog

    Retrieves ModeratorAction records. These records are a log of Mods using their Mod powers. Generally, if an action 1) modifies the database and 2) requires that the acting user be a mod to perform the action, it will get logged.

    Note

    A mod editing/deleting their own content will not get logged, even if they use a Moderator-only API call to do it.

    URL Query Parameters:

    • ?start=INT - the offset from the anchor to start. Offset only counts twarrts that pass the filters.

    • ?limit=INT - the maximum number of twarrts to retrieve: 1-200, default is 50

    Throws

    403 error if the user is not an admin.

    Declaration

    Swift

    func moderatorActionLogHandler(_ req: Request) async throws -> ModeratorActionLogResponseData

    Return Value

    An array of ModeratorActionLogData records.

    Show on GitHub

  • GET /api/v3/mod/twarrt/ID

    Moderator only. Returns info admins and moderators need to review a twarrt. Works if twarrt has been deleted. Shows twarrt’s quarantine and reviewed states.

    The TwarrtModerationData contains:

    • The current twarrt contents, even if its deleted
    • Previous edits of the twarrt
    • Reports against the twarrt

    • The twarrt’s current deletion and moderation status.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func twarrtModerationHandler(_ req: Request) async throws -> TwarrtModerationData

    Parameters

    twarrtID

    in URL path.

    Return Value

    TwarrtModerationData containing a bunch of data pertinient to moderating the twarrt.

    Show on GitHub

  • POST /api/v3/mod/twarrt/ID/setstate/STRING

    Moderator only. Sets the moderation state enum on the twarrt identified by ID to the ContentModerationStatus in STRING. Logs the action to the moderator log unless the user owns the twarrt.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func twarrtSetModerationStateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    twarrtID

    in URL path.
    moderationState

    in URL path. Value must match a ContentModerationStatus rawValue.

    Return Value

    HTTPStatus .ok if the requested moderation status was set.

    Show on GitHub

  • GET /api/v3/mod/forumpost/ID

    Moderator only. Returns info admins and moderators need to review a forumPost. Works if forumPost has been deleted. Shows forumPost’s quarantine and reviewed states.

    The ForumPostModerationData contains:

    • The current post contents, even if its deleted
    • Previous edits of the post
    • Reports against the post

    • The post’s current deletion and moderation status.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func forumPostModerationHandler(_ req: Request) async throws -> ForumPostModerationData

    Parameters

    postID

    in URL path.

    Return Value

    ForumPostModerationData containing a bunch of data pertinient to moderating the post.

    Show on GitHub

  • POST /api/v3/mod/forumpost/ID/setstate/STRING

    Moderator only. Sets the moderation state enum on the post idententified by ID to the ContentModerationStatus in STRING. Logs the action to the moderator log unless the user owns the post.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func forumPostSetModerationStateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    postID

    in URL path.
    moderationState

    in URL path. Value must match a ContentModerationStatus rawValue.

    Return Value

    HTTPStatus .ok if the requested moderation status was set.

    Show on GitHub

  • GET /api/v3/mod/forum/ID

    Moderator only. Returns info admins and moderators need to review a forum. Works if forum has been deleted. Shows forum’s quarantine and reviewed states. Reports against forums should be reserved for reporting problems with the forum’s title. Likely, they’ll also get used to report problems with individual posts.

    The ForumModerationData contains:

    • The current forum contents, even if its deleted
    • Previous edits of the forum
    • Reports against the forum

    • The forum’s current deletion and moderation status.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func forumModerationHandler(_ req: Request) async throws -> ForumModerationData

    Parameters

    forumID

    in URL path.

    Return Value

    ForumModerationData containing a bunch of data pertinient to moderating the forum.

    Show on GitHub

  • POST /api/v3/mod/forum/ID/setstate/STRING

    Moderator only. Sets the moderation state enum on the forum idententified by ID to the ContentModerationStatus in STRING. Logs the action to the moderator log unless the current user owns the forum.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func forumSetModerationStateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    forumID

    in URL path.
    moderationState

    in URL path. Value must match a ContentModerationStatus rawValue.

    Return Value

    HTTPStatus .ok if the requested moderation status was set.

    Show on GitHub

  • `POST /api/v3/mod/forum/:forum_ID/setcategory/:category_ID

    Moderator only. Moves the indicated forum into the indicated category. Logs the action to the moderation log.

    Declaration

    Swift

    func forumSetCategoryHandler(_ req: Request) async throws -> HTTPStatus
    Show on GitHub

  • GET /api/v3/mod/fez/ID

    Moderator only. Returns info admins and moderators need to review a Fez. Works if fez has been deleted. Shows fez’s quarantine and reviewed states.

    The FezModerationData contains:

    • The current fez contents, even if its deleted
    • Previous edits of the fez
    • Reports against the fez

    • The fez’s current deletion and moderation status.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func fezModerationHandler(_ req: Request) async throws -> FezModerationData

    Parameters

    fezID

    in URL path.

    Return Value

    FezModerationData containing a bunch of data pertinient to moderating the forum.

    Show on GitHub

  • POST /api/v3/mod/fez/ID/setstate/STRING

    Moderator only. Sets the moderation state enum on the fez identified by ID to the ContentModerationStatus in STRING. Logs the action to the moderator log unless the current user owns the fez.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func fezSetModerationStateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    fezID

    in URL path.
    moderationState

    in URL path. Value must match a ContentModerationStatus rawValue.

    Return Value

    HTTPStatus .ok if the requested moderation status was set.

    Show on GitHub

  • GET /api/v3/mod/fezpost/:post_id

    Moderator only. Returns info admins and moderators need to review a Fez post. Works if post has been deleted. Shows fez’s quarantine and reviewed states. Unlike most other content types, Fez Posts cannot be edited (although they may be deleted).

    The FezPostModerationData contains:

    • The current post contents, even if its deleted
    • Reports against the post

    • The post’s current deletion and moderation status.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func fezPostModerationHandler(_ req: Request) async throws -> FezPostModerationData

    Parameters

    fezPostID

    in URL path.

    Return Value

    FezPostModerationData containing a bunch of data pertinient to moderating the forum.

    Show on GitHub

  • POST /api/v3/mod/fezpost/:post_id/setstate/STRING

    Moderator only. Sets the moderation state enum on the fez post identified by ID to the ContentModerationStatus in STRING. Logs the action to the moderator log unless the current user authored the post.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func fezPostSetModerationStateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    fezPostID

    in URL path.
    moderationState

    in URL path. Value must match a ContentModerationStatus rawValue.

    Return Value

    HTTPStatus .ok if the requested moderation status was set.

    Show on GitHub

  • GET /api/v3/mod/profile/ID

    Moderator only. Returns info admins and moderators need to review a User Profile. The returned info pertains to the user’s profile and avatar image – for example, the web site puts the button allowing mods to edit a user’s profile fields on this page.

    The ProfileModerationData contains:

    • The user’s profile info and avatar
    • Previous edits of the profile and avatar
    • Reports against the user’s profile

    • The user’s current moderation status.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func profileModerationHandler(_ req: Request) async throws -> ProfileModerationData

    Parameters

    userID

    in URL path.

    Return Value

    ProfileModerationData containing a bunch of data pertinient to moderating the user’s profile.

    Show on GitHub

  • POST /api/v3/mod/profile/ID/setstate/STRING

    Moderator only. Sets the moderation state enum on the profile idententified by userID to the ContentModerationStatus in STRING. Logs the action to the moderator log unless the moderator is changing state on their own profile..

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func profileSetModerationStateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    userID

    in URL path.
    moderationState

    in URL path. Value must match a ContentModerationStatus rawValue.

    Return Value

    HTTPStatus .ok if the requested moderation status was set.

    Show on GitHub

  • GET /api/v3/mod/user/ID

    Moderator only. Returns info admins and moderators need to review a User. User moderation in this context means actions taken against the User account itself, such as banning and temp-quarantining. These actions don’t edit or remove content but prevent the user from creating any more content.

    The UserModerationData contains:

    • UserHeaders for the User’s primary account and any sub-accounts.
    • Reports against content authored by any of the above accounts, for all content types (twarrt, forum posts, profile, user image)
    • The user’s current access level.

    • Any temp ban the user has.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userModerationHandler(_ req: Request) async throws -> UserModerationData

    Parameters

    userID

    in URL path.

    Return Value

    UserModerationData containing a bunch of data pertinient to moderating the forum.

    Show on GitHub

  • POST /api/v3/mod/user/ID/setaccesslevel/STRING

    Moderator only. Sets the accessLevel enum on the user idententified by userID to the UserAccessLevel in STRING. Moderators (and above) cannot use this method to change the access level of other mods (and above). Nor can they use this to reduce their own access level to non-moderator status.

    This method cannot be used to elevate access level to moderator or higher. APIs to do this are in AdminController.

    The primary account and all sub-accounts linked to the given User account are affected by the change in access level. The passed-in UserID may be either a primary or sub-account.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userSetAccessLevelHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    userID

    in URL path.
    accessLevel

    in URL path. Value must match a UserAccessLevel rawValue.

    Return Value

    HTTPStatus .ok if the requested access level was set.

    Show on GitHub

  • POST /api/v3/mod/user/ID/tempquarantine/INT

    Moderator only. Applies a tempory quarantine on a user for INT hours, starting immediately. While quarantined, the user may not create or edit content, but can still read others’ content. They can still talk in private Seamail chats.

    The primary account and all sub-accounts linked to the given User account are affected by the temporary ban. The passed-in UserID may be either a primary or sub-account.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func applyUserTempQuarantine(_ req: Request) async throws -> HTTPStatus

    Parameters

    userID

    in URL path.
    quarantineHours

    in URL path. Must be a integer number.

    Return Value

    HTTPStatus .ok if the requested quarantine was set.

    Show on GitHub

Micro Karaoke Moderation

  • getFullSongList(_:) Asynchronous

    GET /api/v3/mod/microkaraoke/songlist

    Gets info on all the songs that are in Micro Karaoke, including ones being built.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func getFullSongList(_ req: Request) async throws -> [MicroKaraokeCompletedSong]

    Return Value

    [MicroKaraokeCompletedSong] with info on all the completed songs that can be viewed.

    Show on GitHub
  • getSongInfo(_:) Asynchronous

    GET /api/v3/mod/microkaraoke/song/:song_id

    Gets info on a single song in Micro Karaoke..

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func getSongInfo(_ req: Request) async throws -> MicroKaraokeCompletedSong

    Return Value

    MicroKaraokeCompletedSong with info on the song with the given songID.

    Show on GitHub

  • GET /api/v3/mod/microkaraoke/snippets/:song_id

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func getSnippetsForModeration(_ req: Request) async throws -> [MicroKaraokeSnippetModeration]

    Parameters

    song_id

    The song to get a manifest for.
    Show on GitHub
  • deleteSnippet(_:) Asynchronous

    POST /api/v3/mod/microkaraoke/snippet/:snippet_id/delete DELETE /api/v3/mod/microkaraoke/snippet/:snippet_id/

    Moderator only. By design, users may not delete their own submissions.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func deleteSnippet(_ req: Request) async throws -> HTTPStatus

    Parameters

    snippet_id

    The snippet ID to delete. NOT the snippet index–the index just tells you where the snippet gets inserted into its song.
    Show on GitHub
  • approveSong(_:) Asynchronous

    POST /api/v3/mod/microkaraoke/approve/:song_id

    Approve a song for release. Once approved, notifications are sent out to each user that sung a clip in the song. For this reason, there is not currently an ‘unapprove’ action, as re-approving would currently re-send all the notifications. If an approved song contains an objectionable clip, use the mod tools to delete the clip.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func approveSong(_ req: Request) async throws -> HTTPStatus

    Parameters

    song_id

    The song ID to approve.

    Return Value

    HTTP Status`

    Show on GitHub