Moderation API endpoints for Artemis branches

The Moderation API gives branch moderators and site admins programmatic control over content and user management. All moderation endpoints require the authenticated user to be a moderator of the target branch with the appropriate permission set, or a site admin. Most endpoints consume the modposts or modcontributors OAuth2 scope.

POST /api/remove

Removes a post or comment from all branch listings. Moderators can mark the removal as spam, which trains the spam filter, or as a plain removal, which does not.

string

required

Fullname of the post (t3_) or comment (t1_) to remove.

spam

boolean

default:"true"

When true, the removal is treated as a spam action and the item is used to train the spam classifier. When false, the item is removed without spam classification.

# Remove a post and mark it as spam
curl -X POST https://<your-artemis-instance>/api/remove \
  -H "Authorization: Bearer <token>" \
  -d "id=t3_abc12&spam=true"

# Remove a comment without spam classification
curl -X POST https://<your-artemis-instance>/api/remove \
  -H "Authorization: Bearer <token>" \
  -d "id=t1_xyz99&spam=false"

Requires the modposts OAuth2 scope. The authenticated user must be a moderator with the posts permission for the branch containing the item.

POST /api/approve

Approves a previously removed post or comment. Approved content is re-inserted into branch listings and any reports on it are discarded.

string

required

Fullname of the post or comment to approve.

curl -X POST https://<your-artemis-instance>/api/approve \
  -H "Authorization: Bearer <token>" \
  -d "id=t3_abc12"

Requires the modposts OAuth2 scope.

If the item was in the spam queue, approving it also trains the spam classifier to recognize similar content as legitimate.

POST /api/distinguish

Adds or removes a moderator or admin sigil on a comment to indicate the author’s role. The sigil appears inline next to the author’s username.

string

required

Fullname of the comment (or post) to distinguish.

how

string

required

The distinguish level. One of:

yes — adds a moderator distinguish [M]. The user must be a moderator of the branch.
no — removes any existing distinguish.
admin — adds an admin distinguish [A]. Admin accounts only.
special — adds a user-specific distinguish. Availability depends on the account.

curl -X POST https://<your-artemis-instance>/api/distinguish \
  -H "Authorization: Bearer <token>" \
  -d "id=t1_xyz99&how=yes"

Requires the modposts OAuth2 scope. When a top-level comment is moderator-distinguished for the first time, the post author receives an inbox notification.

Banning and unbanning users

POST /api/friend (ban)
POST /api/unfriend (unban)

Bans a user from a branch by creating a banned relationship. Requires the modcontributors OAuth2 scope. Issue the request with the branch in context (e.g. from /r/:branch/api/friend).

name

string

required

Username of the user to ban.

type

string

required

Must be banned.

ban_reason

string

A short reason for the ban, shown to the user. Maximum 100 characters.

ban_message

string

A longer message sent to the user explaining the ban. Markdown, maximum 1,000 characters.

note

string

An internal moderator note, not visible to the banned user. Maximum 300 characters.

duration

number

Duration of a temporary ban in days. Range is 1–999. Omit for a permanent ban.

curl -X POST "https://<your-artemis-instance>/r/programming/api/friend" \
  -H "Authorization: Bearer <token>" \
  -d "name=baduser&type=banned&ban_reason=Spam&duration=7"

Lifts a ban on a user. Requires the modcontributors OAuth2 scope.

name

string

Username of the user to unban.

string

Fullname of the user to unban. Provide either name or id.

type

string

required

Must be banned.

curl -X POST "https://<your-artemis-instance>/r/programming/api/unfriend" \
  -H "Authorization: Bearer <token>" \
  -d "name=baduser&type=banned"

Muting and unmuting message authors

Muting prevents a user from sending modmail to the branch for 28 days.

POST /api/mute_message_author
POST /api/unmute_message_author

Mutes the author of a modmail message. Requires the modcontributors OAuth2 scope and that the authenticated user has both access and mail moderator permissions.

string

required

Fullname of the modmail message whose author should be muted.

curl -X POST https://<your-artemis-instance>/api/mute_message_author \
  -H "Authorization: Bearer <token>" \
  -d "id=t4_msg12"

Unmutes the author of a modmail message, restoring their ability to contact the branch via modmail. Requires the modcontributors OAuth2 scope.

string

required

Fullname of the modmail message whose author should be unmuted.

curl -X POST https://<your-artemis-instance>/api/unmute_message_author \
  -H "Authorization: Bearer <token>" \
  -d "id=t4_msg12"

Moderation queues

The following endpoints return paginated listings of items that require moderator attention. All require the authenticated user to be a moderator of the branch.

Mod queue
Reports
Spam queue

Returns unreviewed posts and comments — items that have been reported or caught by the spam filter but not yet actioned by a moderator.

curl -H "Authorization: Bearer <token>" \
     "https://<your-artemis-instance>/r/programming/about/modqueue.json?limit=25"

branch

string

required

The branch name.

only

string

Filter by type. links for posts only, comments for comments only.

after

string

Fullname cursor for forward pagination.

limit

number

default:"25"

Number of items to return. Maximum is 100.

Returns items that users have reported but that have not yet been actioned.

curl -H "Authorization: Bearer <token>" \
     "https://<your-artemis-instance>/r/programming/about/reports.json?limit=25"

branch

string

required

The branch name.

only

string

Filter by type. links for posts only, comments for comments only.

after

string

Fullname cursor for forward pagination.

limit

number

default:"25"

Number of items to return. Maximum is 100.

Returns items that the spam filter removed automatically and that are awaiting moderator review.

curl -H "Authorization: Bearer <token>" \
     "https://<your-artemis-instance>/r/programming/about/spam.json?limit=25"

branch

string

required

The branch name.

only

string

Filter by type. links for posts only, comments for comments only.

after

string

Fullname cursor for forward pagination.

limit

number

default:"25"

Number of items to return. Maximum is 100.

Each queue returns a standard Listing object whose children array contains the flagged items together with their report counts and reasons.

GET /r/:branch/about/log.json

Returns a paginated log of moderator actions taken in the branch. Requires a moderator session or the modlog OAuth2 scope.

branch

string

required

The branch name.

mod

string

Restrict results to actions taken by this moderator username. Accepts a comma-separated list of names, or a to show only admin actions.

type

string

Restrict results to a specific action type. See ModAction.actions in the source for the full list (e.g. removelink, approvecomment, banuser, muteuser, distinguish, setpermissions).

after

string

Fullname cursor for forward pagination.

limit

number

default:"25"

Number of entries to return. Maximum is 500.

curl -H "Authorization: Bearer <token>" \
     "https://<your-artemis-instance>/r/programming/about/log.json?type=banuser&limit=10"

{
  "kind": "Listing",
  "data": {
    "after": "ModAction_abc",
    "before": null,
    "children": [
      {
        "kind": "modaction",
        "data": {
          "id": "ModAction_abc",
          "mod": "mod_alice",
          "action": "banuser",
          "target_fullname": "t2_baduser",
          "target_author": "baduser",
          "sr_id36": "2fwo",
          "sr_name": "programming",
          "details": "7 days",
          "description": "Repeated spam",
          "created_utc": 1714000000
        }
      }
    ]
  }
}

mod

string

Username of the moderator who performed the action.

action

string

The action type (e.g. banuser, removelink, distinguish).

target_fullname

string

Fullname of the item or user the action was applied to.

details

string

Short detail string (e.g. ban duration or remove vs spam).

description

string

Longer moderator-supplied description (e.g. ban reason or note).

created_utc

number

Unix timestamp of when the action occurred.

POST /api/setpermissions

Updates the permission set for a moderator or pending moderator invite in a branch. Requires the modothers OAuth2 scope. Only unlimited moderators or site admins can change another moderator’s permissions.

name

string

required

Username of the moderator whose permissions are being updated.

type

string

required

The relationship type to update. Either moderator (for an existing moderator) or moderator_invite (for a pending invite).

permissions

string

required

A +-prefixed, comma-separated list of permissions to grant, or -all to grant none. Available permissions are all, access, config, flair, mail, posts, and wiki. Pass +all to grant every permission.

curl -X POST "https://<your-artemis-instance>/r/programming/api/setpermissions" \
  -H "Authorization: Bearer <token>" \
  -d "name=mod_bob&type=moderator&permissions=%2Bposts%2C%2Bflair"

Changing a moderator’s permissions is logged to the branch’s mod action log with the action type setpermissions.

Authentication

Endpoints

Developer Guide

Moderation API endpoints for Artemis branches

POST /api/remove

POST /api/approve

POST /api/distinguish

Banning and unbanning users

Muting and unmuting message authors

Moderation queues

GET /r/:branch/about/log.json

POST /api/setpermissions

Build docs developers (and LLMs) love

Authentication

Endpoints

Developer Guide

Documentation Index

​POST /api/remove

​POST /api/approve

​POST /api/distinguish

​Banning and unbanning users

​Muting and unmuting message authors

​Moderation queues

​GET /r/:branch/about/log.json

​POST /api/setpermissions

Build docs developers (and LLMs) love

POST /api/remove

POST /api/approve

POST /api/distinguish

Banning and unbanning users

Muting and unmuting message authors

Moderation queues

GET /r/:branch/about/log.json

POST /api/setpermissions