# Account and domain actions, and handling reports

How operators and moderators act on accounts and domains, decide appeals, handle reports, check what reached a remote server, and read the audit log.
Everything here except account management and checking deliveries (admin API only) can be done through the admin API (`/api/v1/admin/...`, scopes `admin:read` / `admin:write`) and the CLI (`my admin account action` / `my admin domain` / `my admin report` / `my admin appeal`).
The admin API requires role permissions: account management, actions and appeals need `manage_accounts`, domain actions need `manage_domains`, and reports need `manage_reports`.
The CLI connects to the DB directly with the same configuration as the server (`-config` or environment variables) and does not record which user operated it (`issued_by_user_id` and similar fields are NULL, and the actor in the [audit log](#audit-log) is `cli`).

## From a report to an action and an appeal

![The path of a report: it comes in, a moderator reviews it, an action may follow with a notice to the user, and the user may appeal; the right column shows what each step sends to other servers. The list below describes each step.](https://github.com/mycroblog/my/blob/main/docs/operations/images/moderation-lifecycle.svg?raw=true)

From the top of the diagram down:

1. **A report comes in.** A local user files one, another server sends a `Flag` (dropped when its domain has
   `reject_reports`, see [domain actions](#domain-actions)), or a [decision hook](https://mycroblog.dev/next/operations/decision-hooks/) answers `flag`
   ([reports that an external review filed](#reports-that-an-external-review-filed)). A local user who reports an
   account on another server can choose to forward the report, which sends a `Flag` to that server at once.
2. **Review.** The report is `open`, and the moderators get an `admin_report` notification. Resolving it makes it
   `resolved` with the outcome `actioned` or `dismissed`, and a local reporter gets a `report_resolved` notification.
   Reopening puts it back to `open`. Forwarding a report about an account on another server sends a `Flag` to that
   server ([reports](#reports)).
3. **Action.** A moderator issues an [account action](#account-actions) from the report, which resolves the report as
   `actioned`; an action can also be issued without a report. The action has a kind, a reason, and an end time, and
   ends when it is lifted or expires. With `notify_target`, the user gets a `moderation_notice` notification
   ([what the user sees](#what-the-user-sees)). Other servers receive a `Delete` of the posts for `delete_statuses`, an
   `Update` of the actor when a local account's `suspend` or `ban` starts or ends, and a `Reject` / `Undo` of the
   follows that a remote account's `suspend` cuts.
4. **Appeal.** The local user appeals the action. The appeal is `pending`, and the moderators get an `admin_appeal`
   notification. The decision is `upheld` or `overturned`, and the user gets an `appeal_decided` notification.
   Overturning lifts the action and cancels the deletion of a `ban`, so an overturned `suspend` or `ban` of a local
   account sends an `Update` of the actor ([appeals](#appeals)).

Assignments, notes, notices, and appeals stay on this server; only the activities in the right column leave it.

## Moderation and server administration in the web client

The web client splits the staff screens in two.
The navigation shows "Moderation" and "Administration" only to people whose role has at least one permission of that group. Every screen shows only a reason to people without the permission, and the server rejects their requests too.

| Group | Permissions | Screens |
| --- | --- | --- |
| Moderation (`/moderation`) | `manage_reports`, `manage_accounts`, `manage_domains`, `manage_invites`, `view_audit` | Reports (`/moderation/reports`), Appeals (`/moderation/appeals`), Registrations (`/moderation/registrations`), Automated reviews (`/moderation/hook-decisions`), Accounts (`/moderation/accounts`), Sign-up blocks (`/moderation/signup-blocks`), Invites (`/moderation/invites`), Domain actions (`/moderation/domain-actions`), Remote servers (`/moderation/instances`), Audit log (`/moderation/audit-log`) |
| Server administration (`/admin`) | `manage_settings`, `manage_rules`, `manage_roles`, `manage_jobs`, `manage_login_recovery`, `manage_custom_emojis`, `manage_webhooks`, `manage_announcements`, `manage_finance`, `manage_supporters`, `manage_oauth_apps`, `manage_service_closure`, `manage_errors`, `manage_login_providers` | Server settings (`/admin/settings`), Rules (`/admin/rules`), Terms and policies (`/admin/documents`), Link card domains (`/admin/link-card-domains`), the job queue and failed jobs (`/admin/jobs`), Errors (`/admin/errors`, `manage_errors`), UX measurements (`/admin/ux-measurements`, `manage_errors`), Custom emoji (`/admin/custom-emojis`), Announcements (`/admin/announcements`), Webhooks (`/admin/webhooks`), Costs and income (`/admin/finance`, `manage_finance`), Supporters (`/admin/supporters`, `manage_supporters`). `manage_login_recovery` (login recovery: removing two-factor authentication and issuing a password-reset link) and `manage_roles` (granting and revoking an account's roles) appear as sections of an account's Management page (`/moderation/accounts/{id}/manage`, which also needs `manage_accounts`) |

- The badge on "Moderation" is the total of open reports, registrations waiting for approval and appeals waiting for review ([notifications for moderators and the pending counts](#notifications-for-moderators-and-the-pending-counts)). "Administration" shows no count.
- Each group opens on a list of its screens that your role's permissions open, each with a line of what it holds and, for a queue, how many things wait there (Reports counts the open reports, Appeals those waiting for review, Registrations those waiting for approval, Custom emoji the requests waiting for review, Errors the open errors); a group none of whose screens is open to you says why.
  An address of a screen your role does not open says so, with a link to the group's list.
- The built-in `moderator` has only `manage_reports`, `manage_accounts` and `view_audit`, and does not see "Administration". It also does not see the Domain actions and Remote servers screens (`manage_domains`),
  so to delegate those, create a role with that permission and grant it ([granting and revoking roles](https://mycroblog.dev/next/operations/admin-cli/#granting-and-revoking-roles)).
- The admin API paths stay `/api/v1/admin/...` whatever the group, and the scopes are the same pair `admin:read` / `admin:write`. The groups are separated by tags in the API reference (`admin-moderation`, `admin-server`).
  A service outside the server can call the operations of one permission with a permission scope instead ([letting another service use the admin API](#letting-another-service-use-the-admin-api)).
- There is a third group of permissions, "user features" (`view_finance`, `create_custom_emojis`, `start_voice_rooms`, `create_invites`, `keep_posts_longer`, `create_articles`, `create_events`), which lives outside the staff screens. Someone who has only these permissions sees neither "Moderation" nor "Administration",
  and for someone with `view_finance` the navigation shows "Finances" (`/finance`) after Settings.
  Its API is in the user namespace (`GET /api/v1/finance/cost_totals` and `GET /api/v1/finance/income_totals`, scope `read:finance`) and needs no `admin:*` scope. What it shows is set by `finance_viewer_*` in the [instance settings](https://mycroblog.dev/next/operations/instance-settings/).

### Letting another service use the admin API

A service that you run beside the server, one that hands out invites or records costs, say, can call the admin API for one permission without a plugin.

1. Sign up an account for the service, and grant it a role with only the permissions the service needs (for invites, a role with `manage_invites`; [granting and revoking roles](https://mycroblog.dev/next/operations/admin-cli/#granting-and-revoking-roles)).
2. Signed in as that account, register an app in **Settings → Apps → Your apps** whose scopes include the permission scope, `admin:` and the permission: `admin:manage_invites`.
3. Issue a token to the account from the app, with that scope, and give the service the access token and the refresh token.

- The token reaches only the operations of the permissions its scopes name, and only while the account's roles keep them; the audit log records what it does as the account's actions.
- The access token lasts one hour. The service refreshes it with the refresh token and keeps the new refresh token each time: an old one used again revokes the token.
- `manage_roles`, `manage_oauth_apps`, `manage_login_recovery`, `manage_login_providers` and `manage_service_closure` have no permission scope, and no app can ask a staff member for one on the consent screen.
- To stop the service, revoke the app's tokens or delete the app, take the role away, or disable the app in Administration → OAuth apps.

## Account actions

An action is applied to the restriction projection (`account_restrictions`) in the transaction that records it, and takes effect from the next request.

| Kind | Effect on a local account |
| --- | --- |
| `warn` | No restriction (only informs the user) |
| `force_sensitive` | Shows all attachments as sensitive |
| `limit` | Treats posts (including past ones) as followers-only and keeps them off the public timelines |
| `restrict_posting` | Forbids posting, replying, boosting and editing |
| `restrict_interaction` | Forbids following, favoriting, boosting and replying |
| `disable_login` | Forbids use of the app and the API, and revokes active sessions and tokens (the sign-in page still lets the user see the action) |
| `suspend` | Applies all the restrictions above, and hides the profile and posts from everyone but the user |
| `ban` | Applies the same restrictions as `suspend` and deletes the account after 30 days. It cannot be lifted (it is canceled only when an appeal made during those 30 days is overturned) |
| `delete_statuses` | Deletes the given posts. They become invisible even to the user, and the server sends other servers the same `Delete` as when the user deletes them |
| `mark_statuses_sensitive` | Shows the attachments of the given posts as sensitive |

For a remote account you can issue only `limit`, `suspend` and `force_sensitive` (any other kind gives `422` in the admin API and fails in the CLI).
The effect is local to this server. The only things sent to the other server are the `Reject` / `Undo` of follows cut by `suspend`.

| Kind | Effect on a remote account |
| --- | --- |
| `force_sensitive` | Shows all attachments as sensitive |
| `limit` | Treats posts (including past ones) as followers-only, keeps them off the public timelines, and creates no notifications for users who do not follow the account |
| `suspend` | Drops everything received from the account and hides its profile and posts. Cuts follows between the account and local users in both directions (follow requests too), and sends the other server a `Reject` of the account's follows and an `Undo` of the users' follows. Lifting it brings back the display and the server receives from the account again (what was dropped and the follows that were cut during the suspension do not come back) |

- `notify_target` (`-no-notify`) has no meaning for a remote account (no notification reaches it).
- A local user who lost follows to a `suspend` gets one notification (`relationships_severed`) that tells how many followers and follows were lost ([severed follows](#severed-follows)).
- Issuing and lifting are recorded in the [audit log](#audit-log), as with actions on local accounts.

```sh
my admin account action issue -kind suspend -category spam -public-reason "spam" -duration 720h @alice
my admin account action issue -kind limit -report <report id> @bob@remote.example
my admin account action issue -kind delete_statuses -status <status id> -status <status id> @alice
my admin account action issue -kind ban -category legal -public-reason "illegal content" @alice
my admin account action list -active @alice
my admin account action lift -reason "appealed" <action id>
```

In the admin API: `POST /api/v1/admin/accounts/{id}/actions` (the body has `kind`, `reason_category`, `public_reason`, `private_note`, `report_id`, `notify_target`, `expires_in` in seconds and `status_ids`),
`GET /api/v1/admin/accounts/{id}/actions` (filter with `active`), `GET /api/v1/admin/account_actions/{id}`, and `POST .../{id}/lift` (the body `{"reason": "..."}` is optional).

- Name an account with `@username` (local), `@username@domain` (remote) or the account ID in the CLI, and with the account ID in the admin API.
- Several actions stack (the union of their restrictions). Lifting removes only that action's restrictions, and an action with an end time ends by itself at that time (shown as `expired` in lists). An end time is at most ten years away (`expires_in` up to 315360000); a longer one is refused with `422`.
- Sessions and tokens that `disable_login`, `suspend` and `ban` revoked do not come back when you lift the action. The user signs in again.
- A `suspend` or `ban` of a local account sends an Actor `Update` with an emptied profile to the followers' servers and to known servers to show the suspension (Mastodon shows it as "suspended").
  Lifting and expiry send an `Update` with the original profile. Expiry is sent by a job that runs every 5 minutes, so it can be up to 5 minutes late.
- `delete_statuses` and `mark_statuses_sensitive` take 1 to 100 undeleted posts of the target account through `-status` (`status_ids`). They cannot have an end time.
  Lifting `delete_statuses` does not bring back the deleted posts. Lifting `mark_statuses_sensitive` restores the original display.
- A `ban` cannot have an end time and cannot be lifted. It is canceled only when an appeal the user made during the 30 days before deletion is overturned ([appeals](#appeals)). When in doubt, use a `suspend` with an end time.
  Thirty days after the action, a job that runs every hour deletes the account (the account and posts disappear from view, and the server sends a `Delete` to other servers).
- `report_id` (`-report`) can name only a report about the target account. An open report is resolved as `actioned` together with the action (the resolution is also in the audit log). A resolved report does not change.
- `public_reason` is the reason shown to the user and `private_note` is a note for moderators only. `notify_target` (true by default; false with `-no-notify` in the CLI) decides whether the user is informed.

### What the user sees

- An action with `notify_target` true reaches the user as a notification (`moderation_notice`). It carries the kind, the reason category, `public_reason`, the end time and the state. The kind and the category also come back as display names in the user's UI language.
- The user can check the actions against them with the first-party `GET /api/v1/moderation/actions` (filter with `active`), newest first. Actions with `notify_target` false and lifted or expired actions are listed too.
- `private_note`, the report, who took the action and the reason for lifting are never shown to the user.
- A user can appeal each action once ([appeals](#appeals)). The action list and the action in a notification include whether it can be appealed (`appealable`), the deadline (`appeal_deadline`), and the appeal and its outcome (`appeal`).
- A user under `disable_login`, `suspend` or `ban` cannot use the app or the API but can still sign in on the sign-in page (`/auth/sign_in`). There they see the kind, the reason and the end time of the action in effect
  (for `ban`, the number of days until the account is deleted), and they can appeal from that page ([appeals](#appeals)). The authorization endpoint (`/oauth/authorize`) answers with `403` and issues no token.
  A user under `ban` can sign in until the account is deleted, and the deletion revokes that session too. A user whose own deletion is scheduled, and an account that has been disabled, cannot sign in even on the sign-in page.

### Accounts that their owners deactivated

A user can deactivate their own account from the account settings, after entering their password or a
two-factor code again, or confirming with a passkey (a user with none of these signs in again at a linked
login provider). The account is not a moderation action and moderators cannot deactivate anyone:

- The profile and posts are hidden from everyone but moderators, and other servers receive an `Update` of the
  actor marked `suspended`, so they may show the account as suspended. Every session and token of the user ends.
  Where the server sends mail, one email states the date of the deletion; no other email is sent before it.
- Nothing reaches the account: mentions and direct messages are dropped, no notifications, emails, or Web Push are
  made, and new followers are refused. Favourites and boosts are counted. Existing follows stay.
- The user signs in to a server page, which shows the date of the deletion and lets them reactivate or delete the
  account. Reactivating brings everything back. The next deactivation has to wait 24 hours.
- Thirty days after the deactivation, the hourly job deletes the account. A reactivation after that date is refused
  even if the job has not run yet. The username is not released.

Moderators see the state `deactivated` in the account list (`state=deactivated`), and can still read reports about
the account and act on it. A moderation action does not change the date of the deletion, except a `ban`, which
replaces it with its own: from then on the user cannot reactivate. A suspension sends nothing to other servers while the
account is deactivated, and it stays in effect after the user reactivates. A user cannot deactivate an account while
moderation keeps it from signing in, while its deletion is scheduled, after it moved, while its registration waits
for review, while a paid subscription is still running (including one set to end at the end of its period), or when
it is the only administrator who can sign in. A deactivated administrator does not count as one who can. If a
deactivated administrator's date passes while no other administrator can sign in, the hourly job does not delete the
account and logs a warning. That administrator can no longer sign in either, so create another administrator with
`my admin create`; the next run then deletes the account.

## Appeals

A local user can appeal an action against them.
A moderator reviews the appeal and either upholds it (`uphold`) or overturns it (`overturn`).

```sh
my admin appeal list -state pending
my admin appeal uphold -reason "The posts were spam." <appeal id>
my admin appeal overturn -reason "Sorry, our mistake." <appeal id>
```

The user appeals with `POST /api/v1/moderation/actions/{id}/appeal` (scope `write:accounts`, body `{"text": "..."}`).
A user under `disable_login`, `suspend` or `ban` cannot get an access token and appeals through the per-action form on the sign-in page (`POST /auth/appeal`).
While [sign-in is limited to login providers](https://mycroblog.dev/next/operations/login-providers/#limit-sign-in-to-login-providers), such a user reaches the form only through a linked provider.
The page shows the form and the deadline for an action that can be appealed, the content and outcome for an action already appealed, and the reason for an action whose deadline has passed or that cannot be appealed. For a rejected appeal it shows the reason.
In the admin API: `GET /api/v1/admin/appeals` (filter with `state`), `GET .../{id}`, and `POST .../{id}/uphold` and `POST .../{id}/overturn` (the body `{"public_reason": "..."}` is optional). They need the `manage_accounts` permission.
In the web client, Moderation → Appeals (`/moderation/appeals`) lists the appeals waiting for review, or all of them; an appeal's page (`/moderation/appeals/{id}`) shows what the user wrote and the action, with the reason to tell the user and "Uphold" and "Overturn", each asked first.

- An action can be appealed once, and the text is 1 to 2,000 characters. The deadline is the number of days in the instance setting `appeal_window_days` after the action (default 180 days, 20 to 365; see [instance settings](https://mycroblog.dev/next/operations/instance-settings/)).
  An action past the deadline and a second appeal give `422` (`/api/v1/problems/appeal-window-closed` and `/api/v1/problems/already-appealed`).
- A `ban` can be appealed until the account is deleted (30 days after the action, or until the `appeal_window_days` deadline if that is shorter). A `ban` of a deleted account gives `422` (`/api/v1/problems/not-appealable`). A lifted or expired action can still be appealed within the deadline.
- When a user appeals, people with `manage_accounts` get a notification (`admin_appeal`). When it is reviewed, the user gets a notification (`appeal_decided`) and can see the outcome and `public_reason`. The reviewer is not shown.
- Overturning lifts the action in the same transaction (the same effect as `lift`, with an empty lift reason). Overturning `delete_statuses` does not bring back the deleted posts. An action already lifted before the review stays as it is.
- Overturning a `ban` also cancels the scheduled account deletion in the same transaction (the audit log records `account_deletion_canceled`), ends the suspension, and sends the original profile `Update` to other servers. Revoked sessions and tokens do not come back, so the user signs in again.
  If the account was deleted before the review, it cannot be overturned (`422`, `/api/v1/problems/not-appealable`; upholding is still possible).
- A review happens once. Reviewing again with the same outcome changes nothing, and the opposite outcome gives `409` (`/api/v1/problems/appeal-decided`).

## Account management

Searching accounts, viewing their details and revealing IP addresses and email addresses are done through the admin API and need the `manage_accounts` permission.

In the web client, an account has three pages, with links between them under the page title:

- **Review** (`/moderation/accounts/{id}`): the account's state and restrictions, its registration and who invited it, the form for a new action (opened from a report with "Act on this account", the form also offers the actions on the report's posts, and the action resolves the report), the newest actions on it with their reasons, with "All actions" to its Actions page when there may be more, and its reports, newest first, the rest under "Show more".
- **Actions** (`/moderation/accounts/{id}/actions`): every action on the account, or those in effect, a page at a time. Each action opens its own page (`/moderation/accounts/{id}/actions/{action id}`) with all its details and, while it is in effect, "Lift" with a reason for the moderators. A ban's page has no "Lift": only overturning its appeal undoes it.
- **Management** (`/moderation/accounts/{id}/manage`): for a local account, its roles (`manage_roles`), its email suppression, removing two-factor authentication and issuing a password reset link (`manage_login_recovery`), and its email and IP addresses, shown only after "Show", with its sign-ins and the accounts that used the same IP addresses, each list newest first with the rest under "Show more" (each press reads a page, recorded in the audit log), and a link to those of the same email domain; for a remote account, fetching its posts again from its server (`manage_domains`). Each section appears only to people with its permission.

Staff act only on lower ranks: issuing or lifting an action, deciding an appeal, lifting an email suppression, revealing private data, issuing a password reset link, and removing two-factor authentication need the highest `position` among your roles to be above that of every role of the target.
A higher or equal rank, your own account included, returns `403` with the problem type `/api/v1/problems/target-outranks-actor`, so a moderator cannot ban an administrator and one administrator cannot ban another. The `my admin` commands have no such limit.
An action that keeps the only administrator who can sign in from signing in (`disable_login`, `suspend`, `ban`) is refused whoever issues it, and that administrator cannot delete their own account (`409` with `/api/v1/problems/last-administrator`). See [admin-cli.md](https://mycroblog.dev/next/operations/admin-cli/) for the roles.

- `GET /api/v1/admin/accounts` returns local and remote accounts, newest first (the instance Actor is excluded).
  You can filter by username prefix (`username`), domain (`domain`), local or remote (`origin`), state (`state`), and, for local accounts, email address (`email`), email domain (`email_domain`) and the IP address used to register or sign in (`ip`).
  You can give only one of `email`, `email_domain` and `ip`. The list does not include IP addresses or email addresses.
- The state is the first that applies from this list: `deleted`, `suspended` (`suspend`, `ban`), `disabled` (`disable_login`), `rejected` and `pending` (registration review), `limited` (`limit`), `active`.
  The state and the restrictions (`restrictions`) come only from actions against the account itself and do not include domain actions.
- `GET /api/v1/admin/accounts/{id}` returns the state and restrictions and, for a local account, the registration application and review, the email confirmation, the roles, and up to 20 actions and reports, newest first. `GET /api/v1/admin/reports?target_account_id={id}` pages through all the reports about an account.
- `POST /api/v1/admin/accounts/{id}/reveal` returns a local account's email address, the IP addresses and User-Agents of registration and sign-ins (20 entries, newest first), and other accounts that used the same IP address (up to 20 per IP address).
  `GET /api/v1/admin/accounts/{id}/sign_ins` and `GET /api/v1/admin/accounts/{id}/same_ip_accounts?ip=` page through all of them.
  Every call of these three records `revealed_private_data` in the audit log, and the data is returned only if the record could be written. IP addresses are removed after the retention period (180 days by default), so sign-in origins older than that cannot be shown.
- `two_factor_enabled` in `GET /api/v1/admin/accounts/{id}` shows whether the user of a local account uses two-factor authentication (TOTP).
  A user who lost both the authenticator app and the recovery codes can sign in with the password alone once you remove two-factor authentication with `POST /api/v1/admin/accounts/{id}/two_factor/disable`.
  Only users with the permission `manage_login_recovery` can do this, and by default only the built-in administrator role has it (it belongs to server administration; the web client shows the section only to them).
  Removal records `two_factor_disabled` in the audit log. Verify that the person is the account's owner by another route, such as email, before you remove it.
  When an administrator with no other administrator lost it, the operator removes it with the CLI command `my admin account disable-two-factor @alice` (the audit log actor is the CLI).
- On a server that sends mail, a user who forgot the password gets an emailed link for setting a new one from "Forgot your password?" on the sign-in page.
  For a server that does not send mail (`mail = none`), or a user the mail does not reach, an administrator issues the link and hands it over.
  In the admin screens, issue it with "Password reset" on the account's Management page (`/moderation/accounts/{id}/manage`, `POST /api/v1/admin/accounts/{id}/password_reset_link`).
  Only users with the same permission as removing two-factor authentication, `manage_login_recovery`, can issue it, and by default only the built-in administrator role has it (whoever holds the link can get into the account, so a moderator's `manage_accounts` is not enough).
  The issued link is shown once on the spot and can be copied. The server stores only a hash of the link, so you cannot see it later; issue it again if you need to.
  When no administrator is available or the admin screens are not, the operator issues it with the CLI command `my admin account password-reset-link @alice` (the audit log actor is the CLI).
  While [sign-in is limited to login providers](https://mycroblog.dev/next/operations/login-providers/#limit-sign-in-to-login-providers), both still issue the link and say that it does not work until the limit ends.
  The link works for 1 hour and once, and stops working if the password changes by another route afterwards. Either way of issuing records `password_reset_link_issued` in the audit log.
  Anyone who holds the link can set the password, so verify the person by another route such as email and give the link only to them.
  Setting the new password revokes all of the user's sessions and app tokens. Passkeys and two-factor authentication stay.
- `email_suppression` in `GET /api/v1/admin/accounts/{id}` shows that sending to the primary address of a local account is stopped.
  A `hard_bounce` (the destination does not exist) stops all mail except the confirmation mail, and a `complaint` (reported as spam) stops only notification and announcement mail. Password-reset mail stops too, so issue the link above and hand it over if needed.
  When the user asks for a confirmation mail and confirms the address again, the hard-bounce suppression is lifted.
  When you have verified that sending is fine, for example because the user fixed the mailbox, lift it with `POST /api/v1/admin/accounts/{id}/email_suppression/lift` (permission `manage_accounts`). It records `email_suppression_lifted` in the audit log.
- A search reads up to 400 accounts to fill one page. When few accounts match, even a short or empty page can carry `next_cursor`, so keep reading.

## Domain actions

| Kind | Effect |
| --- | --- |
| `suspend` | Stops all delivery, fetching and receiving (receiving gets `403` before the signature is verified). Existing accounts and posts are hidden from timelines and profiles. Cuts follows between local users and the domain's accounts in both directions (nothing is sent to the other side) |
| `limit` | Keeps posts off the public timelines and search, and creates no notifications for users who do not follow the account |
| `reject_media` | Does not fetch media |
| `reject_reports` | Drops reports (`Flag`) from the domain |
| `force_sensitive` | Shows media as sensitive |

```sh
my admin domain issue -kind suspend -public-comment "spam" spam.example
my admin domain issue -kind limit -duration 720h noisy.example
my admin domain list -active
my admin domain lift <action id>
```

In the admin API: `POST /api/v1/admin/domain_actions` (the body has `domain`, `kind`, `public_comment`, `private_note`, `obfuscate` and `expires_in` in seconds),
`GET /api/v1/admin/domain_actions` (filter with `domain` and `active`), `GET .../{id}`, `POST .../{id}/lift`,
and `GET .../impact?domain=`, which counts the follows that a `suspend` of the domain would end.

In the web client, open Moderation → Domain actions (`/moderation/domain-actions`). The list shows each action's domain, public reason, kind, end and state, in effect or all, of every domain or of the one you search for;
"New action" opens the form (`/moderation/domain-actions/new`), and choosing a domain opens the action's page with its reasons and dates, where "Lift" ends it.
A `suspend` asks first: the confirmation says how many follows between local users and the domain's accounts it ends for good, and asks you to type the domain.
The "Domain actions" link on a remote server's page lists only that domain's actions, and "New action" there starts the form with the domain filled in.

- Domains are recorded normalized to the IDNA A-label (lower case, no trailing dot). `例え.jp` and `xn--r8jz45g.jp` are the same domain.
- An action also applies to subdomains (an action on `spam.example` applies to `a.spam.example` too).
- An action is applied to the restriction projection (`domain_restrictions`) and to the timeline restrictions in the transaction that records it, and takes effect from the next delivery, fetch or receipt.
- An action with an end time (`-duration` / `expires_in`, at most ten years) ends by itself at that time. Expiry is not a "lift", so lists show it as `expired`.
- Lifting removes only that action's restrictions. Other actions on the same domain stay. Lifting an already lifted action changes nothing.
- Lists are newest first, and `-active` (`active=true`) shows only the actions in effect.

### Importing and exporting Mastodon CSV

You can pass the list of domain actions to and from Mastodon in the CSV format of Mastodon's domain blocks (`#domain,#severity,#reject_media,#reject_reports,#public_comment,#obfuscate`).
You can import a CSV that Mastodon exported, and Mastodon can import a CSV that this server exported.

```sh
my admin domain export > domain_blocks.csv
my admin domain import domain_blocks.csv                       # only shows what it would do
my admin domain import -apply -only spam.example,bad.example domain_blocks.csv
```

In the admin API: `GET /api/v1/admin/domain_actions/export` (`text/csv`), `POST .../import/preview` (the body has `csv`), and `POST .../import` (the body has `blocks`, the chosen rows, and `private_note`).
A row for this server's own domain is skipped (`own_domain`), and a domain action on it is refused.
In the web client, open Moderation → Domain actions and choose "Mastodon's CSV" (`/moderation/domain-actions/import`): "Save as CSV" saves the file, and the import previews a chosen file before it imports the rows you keep; a `suspend` among them asks first.

| CSV row | Action on this server |
| --- | --- |
| `#severity` is `suspend` (or empty) | `suspend` |
| `#severity` is `silence` | `limit` |
| `#severity` is `noop` | None |
| `#reject_media` / `#reject_reports` is true | Adds `reject_media` / `reject_reports` respectively |

- An import has two steps. First check in the preview which actions each row would issue, choose the rows to keep, and then import (the CLI changes nothing until you add `-apply`, and `-only` chooses rows by domain).
- A row whose domain or a parent domain already has an action of the same kind in effect does not issue that kind (if every kind is already there, it is "already applied"). A second row for the same domain, an invalid row and a row that would issue nothing (`noop` only) are skipped too. Importing the same CSV again does not add actions.
- A CSV without a `#domain` header is read as a list with one domain per line, and every domain gets `suspend` (the same as Mastodon). One import takes up to 5,000 rows.
- Imported actions last "until lifted" and carry the row's public comment and obfuscation and the private note you gave. They appear in the audit log like actions issued one by one (the actor is the person for the API and `cli` for the CLI).
- An export writes one row per domain for the actions in effect. A domain with a `suspend` gets `suspend`, one with a `limit` gets `silence`, and one with neither gets `noop`. A domain with only `force_sensitive`, which Mastodon's domain blocks do not have, is not exported. Private notes and end times are not exported.

### Subscribing to blocklists

Instead of importing a CSV by hand, you can subscribe to a domain blocklist that another server or person publishes at an
`https` URL. The server fetches the list right after you subscribe, every day after that, and when you ask for it, and turns
its rows into domain actions: as drafts that a moderator accepts or rejects (the `draft` mode, the default), or directly at
each fetch (the `automatic` mode).

```sh
my admin domain subscription add -format mastodon_csv -title "Shared blocklist" https://lists.example/blocklist.csv
my admin domain subscription list
my admin domain subscription drafts <subscription id>
my admin domain subscription accept -keys issue:suspend:spam.example <subscription id>
my admin domain subscription reject -all <subscription id>
my admin domain subscription update -mode automatic <subscription id>
my admin domain subscription fetch <subscription id>               # fetch now and print the outcome
my admin domain subscription fetches <subscription id>
my admin domain subscription remove [-lift-actions] <subscription id>
```

In the admin API: `GET` and `POST /api/v1/admin/domain_list_subscriptions`, `GET`, `PATCH` and `DELETE .../{id}`
(`lift_actions=true` lifts the subscription's actions), `POST .../{id}/fetch`, `GET .../{id}/fetches`, `GET .../{id}/drafts`,
and `POST .../{id}/drafts/accept` and `.../drafts/reject` (the body has `keys`, or nothing for every draft). All of them
need `manage_domains`.

In the web client, open Moderation → Domain actions and choose "Blocklist subscriptions"
(`/moderation/domain-actions/subscriptions`). The list shows each subscription's mode and last fetch, with the failures in a
row; "Add subscription" opens the form of the name, the URL, the format and the settings below, and subscribing opens the
subscription's page. That page has four sections: the drafts, which you accept or reject one by one or all together (accepting
drafts that suspend a domain asks first); the fetches, with "Fetch now" and the outcome of each fetch; the settings; and "Stop
subscribing", which asks whether to lift the actions the subscription issued. The notification `admin_domain_list_failing`
links to the list.

| Format | What the list is |
| --- | --- |
| `mastodon_csv` | Mastodon's domain block CSV, read as an import reads it |
| `mastodon_json` | The answer of `GET /api/v1/instance/domain_blocks` of a Mastodon server that publishes its domain blocks. Domains it obfuscates (with `*`) are skipped, and a server that does not publish the list (`401`, `403`, `404`) fails the fetch |
| `plain_text` | One domain per line, each a `suspend` |

What a row issues follows the same table as an import, changed by the subscription's settings: `suspend_as` (`suspend`,
`limit`, or `ignore`; default `suspend`), `silence_as` (`limit` or `ignore`; default `limit`), whether the row's
`reject_media` and `reject_reports` apply (both by default), and whether the actions copy the row's public comment (not by
default).

- A fetch goes through the same guard as the fetches of other servers: a URL, or a redirect, that leads to a private address
  fails. It reads at most 2 MiB and 5,000 rows; a larger list fails the fetch. The server sends the list's `ETag` and
  `Last-Modified` back, so an unchanged list costs little, and a list identical to the last one read changes nothing.
- A fetch that fails changes no action. It is recorded with why it failed (`http_status`, `network`,
  `forbidden_destination`, `too_large`, `too_many_entries`, or `malformed`) and shown in the list of subscriptions and its
  fetches. After 3 failures in a row, the people whose role has `manage_domains` get the notification
  `admin_domain_list_failing`.
- A subscription never lifts nor replaces an action it did not issue. If an action of the same kind already covers the domain,
  on it or on a parent domain, whoever issued it, the subscription issues nothing there. When two subscriptions list the same
  domain, the action of the one that issued it first is in effect; if that one lifts it, the next one issues its own.
- When the list drops a domain, the automatic mode lifts the action the subscription issued on it at the next fetch. If one
  fetch would lift more than 10 actions and more than half of the subscription's, the lifts wait as drafts instead, since a
  broken or empty list looks like that.
- A severity the server does not know (neither `suspend`, `silence`, nor `noop`) always waits as a draft, as a `suspend`
  under the subscription's settings.
- Drafts list what the list would add (`issue`) and remove (`lift`), each with a key such as `issue:suspend:spam.example`.
  A rejected draft does not come back until the list changes the domain's row (an `issue`) or the action ends (a `lift`).
- If a moderator lifts an action that a subscription issued, the subscription does not issue it again until the list changes
  the domain's row.
- Changing the settings applies them at the fetch that the change starts. The URL and the format do not change; subscribe
  again to change them.
- Removing a subscription keeps the actions it issued, which then count as a moderator's, unless you lift them with it.
- The audit log records subscribing, changing, removing, the drafts accepted and rejected, and the fetches asked for by hand.
  The actions of the automatic mode are recorded like other domain actions with `system` as the actor, and are sent to the
  webhooks as `domain_moderation_action.created` and `.lifted`, whose `data` has the `subscription_id`.

### Severed follows

A domain `suspend` and a remote account `suspend` cut follows between local users and the suspended accounts in both directions.

- For a domain `suspend`, a job (`moderation.sever_domain`) that runs after the action is recorded cuts them one local user at a time. Until the job finishes, the follows still show in lists. Accounts on subdomains are cut too.
- For a remote account `suspend`, the follows are cut in the transaction that records the action. A second `suspend` of an account already suspended cuts nothing.
- Each user who lost approved follows gets one notification (`relationships_severed`) that tells how many followers and follows were lost. A user who lost only follow requests gets none.
- Lifting the action does not bring back the cut follows. Users follow again.
- Processing the same action again (for example when a job re-runs) adds no more severed-relationship records or notifications.

### Federating only with allowed servers

The instance setting `federation_scope` decides which servers this server federates with: `open` (the default) federates with every server that no domain action suspends,
and `allowlist` only with the domains on the allowlist and their subdomains, for an organization or a personal server that talks only with servers it knows.

While `federation_scope` is `allowlist`:

- A server without an allow is treated as a suspended domain: its deliveries get `403` before their signatures are checked, nothing is delivered to it or fetched from it, and relays bring nothing in from it.
- An allow covers its subdomains: allowing `friend.example` also allows `social.friend.example`.
- The domain actions still apply to the allowed servers: an allowed domain with a `suspend` stays suspended, and one with a `limit` or `reject_media` stays limited.
- ActivityPub GETs need a signature from an allowed server, whatever `authorized_fetch` says, so that a server without an allow cannot read the public posts. Servers and crawlers that do not sign their GETs get `401`.
- NodeInfo states `metadata.federationScope`, so that other servers can tell.

While it is `open`, the allowlist changes nothing, and it is kept for the next time you switch.

```sh
my admin domain allow add -comment "partner" friend.example
my admin domain allow list
my admin domain allow remove friend.example
my admin federation scope                   # prints the setting
my admin federation scope allowlist         # shows what the switch would end, and changes nothing
my admin federation scope -apply allowlist  # switches
my admin federation scope open
```

In the admin API: `GET /api/v1/admin/domain_allows`, `POST /api/v1/admin/domain_allows` (the body has `domain` and `comment`; a domain already allowed answers `200` and keeps its allow), and `DELETE /api/v1/admin/domain_allows/{domain}`, with the permission `manage_domains`.
`GET /api/v1/admin/settings/federation_scope/impact` counts what the switch would end, with the permission `manage_settings`, and `PATCH /api/v1/admin/settings` changes `federation_scope` like any other setting.
The allowlist holds at most 5,000 domains, and a comment, which is never published, at most 5,000 characters. This server's own domain cannot be allowed.

Switching to `allowlist`, and removing an allow while it is on, ends follows for good:

- Before you switch, read how many approved follows between local users and the servers without an allow the switch would end, how many local users lose one, and the servers with the most of them (the impact above, or `my admin federation scope allowlist` without `-apply`).
- The switch cuts the follows with every server that the allowlist does not allow, in both directions and without telling those servers, as a domain `suspend` does: a job (`moderation.sever_allowlist`) cuts them one local user at a time, and each user who lost approved follows gets one notification (`relationships_severed`) with the counts.
- Removing an allow while `federation_scope` is `allowlist` cuts the follows with the accounts of that domain and of its subdomains that no other allow covers, in the same way. Removing the allow of a subdomain whose parent domain is allowed cuts nothing.
- Switching back to `open`, or allowing the domain again, does not bring back the cut follows. Users follow again.
- Setting `allowlist` when it is already `allowlist` cuts nothing more.

In the web client, open Moderation → Domain actions and choose "Allowed domains" (`/moderation/domain-actions/allowed`) to read,
add and remove allows; removing one asks first, since it cuts the domain off while `federation_scope` is `allowlist`. The
setting itself is "Servers" on the Federation page of the server settings (`/admin/settings/federation`, with the
permission `manage_settings`): choosing "Allowed servers only" and saving shows the follows the switch would end, the local
accounts that lose one, and the servers with the most of them, and saves only once you confirm.

Adding and removing an allow are in the audit log (`domain_allow_added` and `domain_allow_removed`), and the switch is the `setting_changed` of `federation_scope`.

### Publishing the domains you act on

You can publish the `limit` and `suspend` actions in effect through `GET /api/v1/instance/domain_actions`.
The instance setting `domain_actions_visibility` (`off` / `signed_in` / `everyone`, default `off`) decides who sees the list, and
`domain_actions_rationale_visibility` (the same values, default `off`) decides who sees the public comments ([instance settings](https://mycroblog.dev/next/operations/instance-settings/)).

```sh
my instance set domain_actions_visibility signed_in
my instance set domain_actions_rationale_visibility signed_in
```

- With `off` the API returns `404`, and with `signed_in` it returns `401` to a request without an access token.
- There is one entry per action, newest first. An entry has the domain, the SHA-256 of the domain (hex) and the kind, and the public comment for people allowed to see it. Private notes are never returned.
- For an action with `-obfuscate` (`obfuscate`), the middle half of the domain's characters (other than dots) is replaced with `*` (`bad.example` becomes `bad.*****le`).
  Anyone can compare the SHA-256 of a domain they know to check whether it is an obfuscated one.
- `reject_media`, `reject_reports` and `force_sensitive` actions, and lifted or expired actions, are not published.
- The web client's instance information page (`https://<host>/about`) shows this list under the same settings. With `off` the section is not shown, and with `signed_in` people who are not signed in see a note that only signed-in users can see it.

## Refetching remote posts

You can refetch stored remote posts from the other server.
A refetch happens only when you ask for it through the admin API, the CLI or the web client, never periodically.

```sh
my admin refetch status <post ID or URI>
my admin refetch account @bob@remote.example
my admin refetch domain remote.example
```

In the admin API: `POST /api/v1/admin/statuses/{id}/refetch`, `POST /api/v1/admin/accounts/{id}/refetch_statuses` and `POST /api/v1/admin/instances/{domain}/refetch_statuses`. They need the `manage_domains` permission.
In the web client, use "Refetch posts" on the account's Review page (`/moderation/accounts/{id}`, remote accounts) and the remote server screen (`/moderation/instances/{domain}`).

- A post is handled like a received `Update`. If there is a newer version, the server adds a version; it updates poll vote counts; and it does nothing if nothing changed. A post for which the other server returns 410 Gone or a `Tombstone` is deleted. A post that cannot be fetched (404 included) is left as it is.
- For an account, the server refetches up to 1,000 of its newest undeleted stored posts, 100 at a time, one minute apart.
- For a domain, the server refetches from the newest accounts of the domain, up to the 20 newest posts per account and up to 1,000 posts in all, 5 accounts at a time, one minute apart.
- It does not fetch from a domain with a `suspend`, or from a domain that is `unavailable` because deliveries failed. A failed fetch of the same URI is remembered for 1 hour, and a refetch in that time does not fetch it.
- Your request is recorded in the audit log as `status_refetch_queued`, `account_statuses_refetch_queued` or `domain_statuses_refetch_queued`.

## Checking what reached a remote server

When a user asks whether a post, a follow, or an accept reached another server, list the deliveries to that server with the admin API.
It shows each delivery of an activity to an inbox of the server, newest first, with every attempt and what the server answered, the deliveries that succeeded included.
It needs the `manage_domains` permission.
In the web client, the **Deliveries** section of the remote server screen (`/moderation/instances/{domain}`) shows the same list, with its filters by **Activity ID** and **Local account**, and **Show** for each hidden field under **Details** of a masked delivery; the screen says which of them are recorded in the audit log before they run.
The Remote servers list shows only the servers that deliveries failed to reach. To open any other server, enter its domain, a handle on it, or a URL on it in **Open a server** above the list,
or use **Open the account's server** on a remote account's Review page or on a report about a remote account, or the domain in an audit log entry about a domain.

```sh
curl -H "Authorization: Bearer $TOKEN" \
  "https://example.com/api/v1/admin/instances/misskey.io/deliveries"
```

- Each delivery has the activity type (`Create`, `Follow`, `Accept` and so on), when the activity was recorded and when the inbox was added, and its `attempts`, oldest first.
  Each attempt has its `outcome` (`succeeded`, `retryable_failure`, `permanent_failure`, `skipped`), the `signature_scheme` and `status_code` of the response, the `error` of a failure without a response or why nothing was sent, and the time.
  A `succeeded` attempt with `202` means the other server accepted the activity; whether it then shows it is up to that server.
- Attempts are kept for 30 days, so the history goes back 30 days.
- To narrow the list, add `activity_uri=<the activity's ID>`, or `account_id=<a local account's ID>` for the deliveries of one account.
  A query with `account_id` is recorded in the audit log as `account_deliveries_viewed`, with the account and the server; the other queries are not recorded.
- The body of the activity is never shown.

Some deliveries are masked: their sender, activity URI, and inbox are left out, and `mask` says why.

| `mask` | The activity is about |
| --- | --- |
| `private`, `direct`, `local` | a post with that visibility |
| `approves_followers` | a follow, its undo, an accept, or a reject of a local account that approves its followers |
| `unknown` | a post or an account that is gone, so what it was is no longer known |

A shared inbox names no recipient and is always shown; a masked personal inbox in an attempt's error reads `[masked]`.
The type, the times, and every attempt of a masked delivery are shown, so you can still see whether it reached the server.
To see the masked fields of one delivery, use `POST /api/v1/admin/instances/{domain}/deliveries/{id}/reveal`; each call is recorded in the audit log as `delivery_revealed` before anything is shown.

## Reports

Reports (`Flag`) received from other servers enter the report list as open (`open`).

```sh
my admin report list -state open
my admin report show <report id>
my admin report assign <report id> <username>
my admin report unassign <report id>
my admin report resolve -outcome dismissed <report id>
my admin report note <report id> "Same person as an earlier report"
my admin report reopen <report id>
my admin report forward -comment "Spam account, see the linked posts" <report id>
```

In the web client, **Moderation → Reports** (`/moderation/reports`) lists the open reports, the newest first, with who filed each, its category, when, and who handles it.
Its filters (state, category, and who handles it: you or nobody) and the order (the column **Filed**: the newest or the longest-waiting first) stay in the page's address, and **Previous** and **Next** move through the pages.
A report's page (`/moderation/reports/{id}`) shows its state, category, cited rules (a rule retired since says so), who filed it and who handles it, whether it went to the account's server, and how many other reports and actions the account has;
then the account; the comment; the reported posts, a deleted one with when it was deleted; what happened in the voice chat room or the changes of the event; and the notes.
From `wide` the page of the list you came from stands beside it. **Assign to me** and **Unassign**, **Resolve** (**Action taken** or **No action needed**) and **Reopen** are under its title, **Add note** under the notes.

In the admin API: `GET /api/v1/admin/reports` (filter with `state`, `category`, and `assignee`: `me`, `none`, or a local account's ID; `order=oldest` lists the longest-waiting report first instead of the newest), `GET .../{id}`, `POST .../{id}/assign_to_self`, `POST .../{id}/unassign`,
`POST .../{id}/resolve` (body `{"outcome": "actioned" | "dismissed"}`), `POST .../{id}/notes` (body `{"body": "..."}`), `POST .../{id}/reopen` and `POST .../{id}/forward` (body `{"comment": "..."}`, optional).

- An assignment (`assign`) can go only to a local user whose role has `manage_reports`. In the admin API you assign yourself.
- The outcome of a resolution (`resolve`) is `actioned` (an action was taken against the target) or `dismissed` (no action was needed). Resolving a resolved report again does not change the outcome.
- When you issue an action from a report (`report_id` / `-report` of the action), the report is resolved as `actioned` in the same operation.
- A note (`note`) is an internal note that only moderators see, up to 2,000 characters. It is shown neither to the target nor to the reporter. It cannot be edited or deleted.
- Reopening (`reopen`) puts a resolved report back to `open` (the assignment stays). An open report cannot be reopened (`409` in the admin API).
- Forwarding (`forward`, **Send to their server…** at the end of the report's page, which asks first) sends a report about an account on another server to that server, as a `Flag` of your instance actor with the account and the reported posts that still exist. The only text it carries is what you write for that server's moderators when you forward it (`-comment`, `comment` in the admin API, or **Text for their moderators** on the report's page; up to 1,000 characters, none by default). The reporter's comment and the note of an [external review](#reports-that-an-external-review-filed) never leave your server this way, and nothing of the reporter is sent. A report that its reporter chose to forward when filing it went out at once, with the reporter's comment. Forwarding works on a report filed on this server, by a person or by an [external review](#reports-that-an-external-review-filed), open or resolved, that was not forwarded yet; a report received from another server or about a voice chat room or an event cannot be forwarded (`409` `report-not-forwardable` in the admin API, and the report details show no button). A report is sent once: forwarding it again, with any text, or forwarding one that its reporter had forwarded when filing it, changes nothing. `forwarded` in the admin API says whether it was sent, `forwardable` whether you can send it now.
- The report details (`show`, `GET .../{id}`) return the notes, oldest first, with the number of other reports about the target and the number of actions against the target (lifted and expired ones included). The list does not return notes.
- Assignments, resolutions, reopenings, notes and forwards are kept as events (`report_assignments`, `report_resolutions`, `report_reopenings`, `report_notes`, `report_forwards`), and `report_states` holds the current state.
- Moderators can translate the reported posts and the reporter's comment on the report's page, or with `POST .../{id}/statuses/{status_id}/translation` and `POST .../{id}/comment/translation` (body `{"target_language": "en"}`).
  The text goes to a translation provider only while the [instance setting](https://mycroblog.dev/next/operations/instance-settings/) `translation_reports_to_server` is on, and then only to a provider allowed the post's visibility: a moderator's access widens nothing, so a direct post goes only to a provider allowed `direct`, and the comment counts as `private`.
  The comment's translation is not kept, nor is that of a deleted post, and the characters count against the server's monthly limit only. The browser's built-in translation, when `translation_browser` is on, works on the reported posts whatever `translation_reports_to_server` says; the comment, which names no language, is translated only by the server.
- A reporter sees of the target only what they would see of the account otherwise: while it is suspended or blocks them, their report stays listed without the account. Moderators always see the whole target.
- A local reporter gets a notification (`report_resolved`) at the first resolution. Reopening and resolving again adds no notification.
  A reporter can list their own reports with `GET /api/v1/reports` and sees only whether each is open or resolved. The outcome, the action taken, the reason given to the target and the assignee are not shown.

### Reports that an external review filed

A [decision hook](https://mycroblog.dev/next/operations/decision-hooks/) that answers `flag` files a report with your instance actor as the reporter. The report
says so: `hook_origin` in the admin API and the `report.created` webhook, a line in the report details, and `automated` in
`my admin report show`. Its comment is the plugin's note, and its category comes from the reason. It is not forwarded when it
is filed, and resolving it notifies nobody. When the target is on another server, you can forward it
yourself (`forward`): the plugin's note stays on your server, and only the text you write goes out. Cancelling the decision
leaves the report as it is.

### Voice chat rooms

- A local user can report an open voice chat room that they can see (`POST /api/v1/reports` with `voice_room_id`, and `account_id` set to the room's host).
  The report targets the host at that moment and points at the room's settings (name and description) as they were then. It points at no posts and is never forwarded to another server.
- The report details (`GET /api/v1/admin/reports/{id}`) show the room (`voice_room`): every change of its settings, who took part and when they left, who was removed from it, and how it ended.
  The records of who took part are kept for 90 days after the room ends (`voice_participants_retention_days`) and as long as a report points at the room ([record retention](#record-retention-and-holds)).
  There are no recordings and no text chat, so these records are the only evidence.
- A holder of `manage_reports` can end an open room for every participant with `POST /api/v1/admin/voice_rooms/{id}/end` (body `{"reason": "..."}`, optional, up to 500 characters).
  The reason is only for the moderators; the participants see only that the room ended. It works while the voice chat is off too, and the audit log records `voice_room_ended`.
  In the web client, the report's page of an open room has "End the room", which asks first, with the reason.

### Events

- A local user can report an event that they can see, a cancelled one included (`POST /api/v1/reports` with `event_id`, and `account_id` set to the event's organizer).
  The report targets the organizer and points at the event's settings (title, description, and places) as the reporter saw them. An event still polling for a date can be reported and cancelled like any other. It points at no posts and is never forwarded to another server.
- The report details (`GET /api/v1/admin/reports/{id}`) show the event (`event`): its date, whether and how it was cancelled, and every change of its settings, oldest first, with all its places, also those that only the approved attendees saw.
  `reported_revision_id` is the version the reporter saw, so a title or an address changed after the report is still in front of you.
- A holder of `manage_reports` can cancel an event with `POST /api/v1/admin/events/{id}/cancel` (body `{"reason": "..."}`, optional, up to 500 characters).
  The reason is shown with the cancellation to everyone who sees the event. The users who answered going or maybe and the invited users are notified, as of the organizer's own cancellation, and the audit log records `event_cancelled`.
  An event cancelled already answers `409` `event-closed`. In the web client, the report's page of an event has "Cancel the event", which asks first, with the reason.
- A post on the board of an event is reported, reviewed, and deleted like any other post (`status_ids`, with `account_id` set to its writer). Its report is never forwarded, and its deletion never leaves the server.
- Suspending or deleting the organizer cancels the organizer's events that have not started yet, including those still polling for a date (`gathering.cancel_organized`), and notifies their attendees. These cancellations name nobody as the one who cancelled them, and lifting the suspension does not restore them. Events that started already are not cancelled.

## Notifications for moderators and the pending counts

New reports, registrations waiting for approval and appeals reach people with the permission as in-app notifications.

| Notification | When it arrives | Who gets it |
| --- | --- | --- |
| `admin_report` | When the report's target has no other open report (a second or later report about the same account does not notify) | People whose role has `manage_reports`, except the reporter and the report's target |
| `admin_sign_up` | When a registration starts as waiting for approval (approval mode, or `open` on a setup that cannot send mail) | People whose role has `manage_accounts` |
| `admin_appeal` | When an appeal is made against an action | People whose role has `manage_accounts`, except the person who appealed |
| `admin_custom_emoji_request` | When creating a custom emoji or replacing its image is requested | People whose role has `manage_custom_emojis`, except the requester |
| `admin_error_group` | When the server or the web client reports an error of a new kind, or an error group that was resolved happens again on another version of the server | People whose role has `manage_errors` |
| `admin_domain_list_failing` | When the fetch of a subscribed blocklist fails for the third time in a row | People whose role has `manage_domains` |

- `admin_error_group` arrives at most 10 times an hour for the whole server. The rest of the hour fold into one notification
  that says how many more error groups there were. A muted group never notifies. An error that the web client reports for a
  visitor who is not signed in notifies only once a signed-in user's browser reports it too, and its recurrence notifies nobody.
  The error groups are read and resolved, muted, or unmuted through `GET /api/v1/admin/error_groups` and
  `POST /api/v1/admin/error_groups/{id}/resolve` (`/mute`, `/unmute`), which need `manage_errors`.
- Who receives a notification is decided by their permission when the notification is created. A person who later loses the permission no longer sees that kind in their list and unread count. If the permission comes back, they see it again.
- Each kind of notification above also comes by email, on by default. Each person turns each kind on or off in the app and by
  email on the **Notifications** page of the settings (`/settings/notifications` in the web client), which lists only the
  kinds their role receives. A kind turned off in the app is not created for them, so it is neither pushed nor emailed; the counts of
  `GET /api/v1/admin/counts` do not change, because they count the reports, registrations, and appeals themselves.
  With the open reports, the counts also return when the oldest open report was filed (`oldest_open_report_filed_at`).
  The server enqueues the email job in the transaction that records the notification, and the job sends the mail right after the
  commit, without waiting for the notification to be read. If the person has lost the permission or turned that kind's email
  off by the time of sending, or their primary address is not confirmed or its emails are stopped, nothing is sent.
  The mail contains only the kind of notification and a link to the notifications screen, and none of the contents of the report or the account. Its unsubscribe link turns off the email of that kind only.
  With `mail = none`, no mail is sent, and `sends_email` in `GET /api/v1/instance` is `false`.

`GET /api/v1/admin/counts` returns the number of open reports (`open_reports`, needs `manage_reports`), the number of registrations waiting for approval (`pending_registrations`) and the number of appeals waiting for review (`pending_appeals`) (both need `manage_accounts`), the number of custom emoji requests waiting for a decision (`pending_custom_emoji_requests`, needs `manage_custom_emojis`), and the number of open error groups, new, regressed or unmuted (`open_error_groups`, needs `manage_errors`).
Items you lack the permission for are not returned.

## Audit log

Operations by moderators and administrators are recorded one row each in the audit log (`audit_log_entries`) in the same transaction as the operation.
Failed operations and operations that changed nothing are not recorded: lifting an already lifted action, resolving a resolved report, assigning to the same assignee, retiring an already retired rule, moving to the same position, granting a role the user already has, and revoking a role the user does not have.

| Target kind | Operations |
| --- | --- |
| `account` | `account_action_issued` and `account_action_lifted` (issuing and lifting an action against an account), `account_deletion_canceled` (the deletion canceled because an appeal against a `ban` was overturned), `revealed_private_data` (IP addresses and email addresses revealed), `two_factor_disabled` (two-factor authentication removed), `password_reset_link_issued` (a password-reset link issued), `email_suppression_lifted` (mail suppression lifted), `account_moved` (a restricted local account moved to a local account; restrictions are not carried to the destination, so you decide whether to apply them there), `account_statuses_refetch_queued` (refetch of a remote account's posts), `account_deliveries_viewed` (the deliveries of a local account to a server listed; the target name is the handle and the server) |
| `status` | `status_refetch_queued` (refetch of a remote post; the target name is the post URI) |
| `domain` | `domain_action_issued` and `domain_action_lifted` (issuing and lifting a domain action), `domain_statuses_refetch_queued` (refetch of posts of the domain's accounts), `instance_marked_available` (clearing the failures of a server), `delivery_revealed` (the masked sender, activity URI, and inbox of a delivery to the server shown) |
| `report` | `report_assigned`, `report_unassigned`, `report_resolved`, `report_reopened`, `report_note_added`, `report_forwarded` (assigning, unassigning, resolving and reopening a report, adding a note, and forwarding it) |
| `user` | `registration_approved`, `registration_rejected` (registration review) |
| `setting` | `setting_changed` (instance settings), `text_changed` (instance texts) |
| `rule` | `rule_added`, `rule_revised`, `rule_moved`, `rule_retired` (instance rules) |
| `role` | `role_granted`, `role_revoked` (granting and revoking a role for a user), `role_created`, `role_updated`, `role_deleted` (creating, changing and deleting a role) |
| `appeal` | `appeal_upheld`, `appeal_overturned` (appeal review; overturning also records `account_action_lifted` for the action, and `account_deletion_canceled` for a `ban`) |
| `signup_block` | `signup_block_added`, `signup_block_lifted` (adding and lifting a sign-up block) |
| `hook_decision` | `hook_decision_applied` (the server acted on an external review's verdict and left state; the actor is the system), `hook_decision_overridden` (a moderator cancelled the decision, also by overturning its appeal), `hook_appeal_upheld` (a moderator upheld the appeal of a refused post, and the decision stays) |
| `custom_emoji` | `custom_emoji_created`, `custom_emoji_image_replaced`, `custom_emoji_copied`, `custom_emoji_updated`, `custom_emoji_enabled`, `custom_emoji_disabled`, `custom_emoji_deleted` (registering a custom emoji, replacing its image, copying an emoji from another server, changing, enabling, disabling and deleting it) |
| `webhook` | `webhook_created`, `webhook_updated`, `webhook_deleted`, `webhook_enabled`, `webhook_disabled`, `webhook_secret_rotated` (creating, changing, deleting, enabling and disabling a webhook, and regenerating its secret) |
| `announcement` | `announcement_created`, `announcement_updated`, `announcement_published`, `announcement_withdrawn`, `announcement_deleted` (creating, changing, publishing and withdrawing an announcement, and deleting a draft) |
| `invite` | `invite_created`, `invite_revoked` (creating and revoking an invite; the target name is the first 4 characters of the code) |
| `billing_source` | `billing_import_queued` (a billing import was started by hand; the target name is the provider's name) |
| `cost_item` | `cost_item_created`, `cost_item_relabeled`, `cost_item_price_revised`, `cost_item_end_changed`, `cost_item_deleted` (registering a cost, changing its name and the like, revising its amount, changing its end date, and deleting it; the target name is the item's name) |
| `supporter_program` | `supporter_program_enabled`, `supporter_program_disabled` (enabling and disabling billing; the target name is the payment provider's name), and `supporter_tips_enabled`, `supporter_tips_revised`, `supporter_tips_disabled` (enabling the tips, changing their amounts, and disabling them; the target name is the currency and the amounts in minor units) |
| `supporter_plan` | `supporter_plan_created`, `supporter_plan_revised`, `supporter_plan_retired` (creating, changing and retiring a supporter plan; the target name is the plan's name) |
| `supporter_subscription` | `supporter_subscription_ended` (an administrator ended a subscription at once; the target name is the plan's name and the user's handle) |
| `custom_emoji_request` | `custom_emoji_request_submitted`, `custom_emoji_request_withdrawn`, `custom_emoji_request_approved`, `custom_emoji_request_rejected` (submitting, withdrawing, approving and rejecting a custom emoji request; the target name is the `:shortcode:`) |
| `payment_provider` | `payment_reconcile_queued` (reconciliation with the payment provider was started by hand; the target name is the provider's name) |
| `oauth_client` | `oauth_client_disabled`, `oauth_client_enabled` (disabling and enabling an OAuth client; disabling revokes all its tokens; the target name is the client's name and `client_id`) |
| `oauth_client_host` | `oauth_client_host_denied`, `oauth_client_host_allowed` (denying and revoking the denial of a Client ID Metadata Document host; denying revokes the tokens of that host's clients; the target name is the host) |
| `instance` | `service_closure_announced`, `service_closure_withdrawn`, `service_closure_closed`, `service_closure_delivery_completed` (announcing the closure of the service or changing the date, withdrawing the announcement, closing, and completing the delivery of the closure; the target name is `service_closure`) |
| `voice_room` | `voice_room_ended` (a moderator ended an open voice chat room; the target name is the room ID, since the name goes when the account that wrote it is erased; the report details show the name) |
| `event` | `event_cancelled` (a moderator cancelled an event; the target name is the event ID, since the title goes when the account that wrote it is erased; the report details show the title) |
| `domain_allow` | `domain_allow_added`, `domain_allow_removed` (adding a domain to the allowlist of federation and removing it; see [federating only with allowed servers](#federating-only-with-allowed-servers); the target name is the domain) |
| `link_card_domain` | `link_card_domain_fetch_stopped`, `link_card_domain_images_stopped`, `link_card_domain_rule_removed` (setting a rule of the link card crawler on a domain, and removing it; see [link card domains](https://mycroblog.dev/next/operations/instance-settings/#link-card-domains)) |
| `login_provider` | `login_provider_created`, `login_provider_updated`, `login_provider_deleted`, `login_provider_enabled`, `login_provider_disabled`, `login_provider_secret_rotated` (adding, changing, deleting, enabling and disabling an external login provider, and replacing its client secret; the target name is the provider's display name) |
| `domain_list_subscription` | `domain_list_subscription_created`, `domain_list_subscription_updated`, `domain_list_subscription_deleted` (subscribing to a blocklist, changing its settings, and removing it), `domain_list_draft_accepted` and `domain_list_draft_rejected` (accepting a draft, which also records the domain action, and rejecting one), `domain_list_fetch_queued` (a fetch asked for by hand); the target name is the subscription's title; see [subscribing to blocklists](#subscribing-to-blocklists) |

The list shows whether the target still exists. Accounts, reports, appeals and sign-up blocks that disappeared after their retention period, removed allows, and deleted roles, custom emoji and webhooks, show only the name at the time of recording and no link to a screen.

```sh
my admin audit list
my admin audit list -actor alice -action domain_action_issued
my admin audit list -target-kind domain -target-id spam.example
```

In the admin API: `GET /api/v1/admin/audit_log` (filter with `actor_account_id`, `action`, `target_kind` and `target_id`). It needs the `view_audit` permission.
In the web client, open Moderation → Audit log (`/moderation/audit-log`): each entry reads as a sentence of who did what to what, newest first, the person and the target linked to their screens.
Filter it by who did it (you, or the person of an entry's "Their other operations"), by the kind of target and then of operation, and by one target (an entry's "Other operations on this").

- A row is the actor (the user for `user`, or `cli` for the CLI), the operation, the target kind and ID, the target's display name, the ID of the original record, and the time.
  The target ID is the ID of the account, report, appeal, user, rule, role or sign-up block; for a domain action it is the domain; for settings and texts it is the key.
- The target's display name (`@alice`, `@bob@example.com`, a domain, a setting key, the text of a rule; for a text its key, for a role its key and the user's handle, for a sign-up block its kind and value) is a copy taken at recording time, so it is still readable after the target is gone.
  Each API row also returns whether the target still exists (`target_exists`), which is `false` for accounts, reports, appeals and sign-up blocks that are gone. The web audit log shows only the display name, without a link, for a target that is gone.
- The text of reasons and notes is not copied. Look it up through the ID of the original record (the action, assignment, resolution, reopening, note, review, or the version of a setting or rule).
- The list is newest first with keyset paging (`-before <entry id>` in the CLI).
- There is no API or CLI to update or delete the audit log. Old rows are removed after the [retention period](#record-retention-and-holds).

## Record retention and holds

After the retention period for each kind of record, hourly jobs (`moderation.purge_records`, `identity.purge_origins`, `voice.purge_records`, and `gathering.purge_records`) remove moderation records.
You can change the periods in the instance settings, but not below the lower limit ([instance settings](https://mycroblog.dev/next/operations/instance-settings/)). A changed period takes effect from the next run. A released retention hold, with its reason, is removed once the retention period for moderation actions has passed since its release.

| Record | Setting | Default | Lower limit | Starts from |
| --- | --- | --- | --- | --- |
| Sign-in IP address and User-Agent | `session_origins_retention_days` | 180 days | 90 days | The sign-in |
| Registration IP address | `registration_origins_retention_days` | 180 days | 90 days | The registration |
| Reports (comment, target posts, notes, assignments, resolutions, reopenings) | `reports_retention_days` | 365 days | 180 days | The last resolution |
| Actions against accounts (reason, note, target posts, lifting) and appeals | `moderation_actions_retention_days` | 365 days | 180 days | The end of the action |
| Audit log | `audit_log_retention_days` | 730 days | 365 days | The record |
| Sign-up blocks | None (cannot be changed) | 30 days | n/a | The earlier of lifting and expiry |
| Who took part in a voice chat room (participations, speakers and listeners, raised hands, invitations, removals) | `voice_participants_retention_days` | 90 days | 30 days | The end of the room |
| The decisions of the [decision hooks](https://mycroblog.dev/next/operations/decision-hooks/#the-decisions) | `hook_decisions_retention_days` | 90 days | 30 days | The decision |
| The answers, approvals, invitations, votes on the candidate dates, and board posts of an event | `event_records_retention_days` | 90 days | 30 days | The earlier of the end of the event (for an event whose date was never fixed, the end of its last candidate date) and its cancellation |

- Open reports are never removed. A report that an action refers to (`report_id` of the action) stays until that action is removed.
- The end of an action is the earlier of lifting and expiry. For an action that was appealed, if the review comes later than that, the end is the time of the review, and the action is kept while the appeal waits for review.
  `warn` and `delete_statuses` have no lasting effect, so the end is the time they were issued. An action without an end (a `ban`, a `suspend` without an end time, and so on) is not removed until it is lifted.
- A deleted post disappears from view at once, and the hourly job `content.purge_deleted_statuses` removes its text, media, and poll 7 days later, once its `Delete` has had time to reach the other servers; the record of its URI stays.
  Posts that a report or an action points to are not physically deleted, with their attached media, until that report or action is removed. Remote posts also stay beyond the retention period (including the instance setting `remote_status_max_retention_days`).
- A sign-up block that has neither a lift nor an end time stays as long as it is in effect.
- The records of who took part in a voice chat room that a report points at stay until that report is removed. The room itself (its name, description, hosts, and how it ended) is never removed.
- The answers, votes, and invitations of an event that a report points at stay until that report is removed, and so do those that name an account under a hold. The event itself (its settings and places, its date and candidate dates, its co-organizers, and its cancellation) is never removed; once its answers are gone, it counts nobody as going.
- One job run removes only a capped number of rows per kind (100 at a time, 20 times, for actions, reports and sign-up blocks; 1,000 rows at a time, 20 times, for the audit log). The next run removes the rest.

### Holds

While a court order forbids erasure (Japan's Information Distribution Platform Act, Article 16) or a disclosure request is being handled, you can stop erasure per account.

```sh
my admin retention hold -reason "court order 2026-123" @alice
my admin retention list -account @alice
my admin retention release <hold id>
```

- For an account under a hold, its actions and appeals, the reports about it and the reports it made, the audit logs of those, the sign-in and registration IP addresses, its posts, and the records of the voice chat rooms that it took part in or acted in are not removed after the retention period.
  A sign-up block created from that account's ban is also kept past 30 days after lifting or expiry.
- You can place several holds on one account. When you release them all, records past their period are removed on the next run. Releasing an already released hold changes nothing.
- Holds and their release are done only with the CLI, and the actor in the record is the CLI.
- The data of a deleted account (one whose `ban` reached its date, one the user deleted, or a remote account that its server deleted) is erased 7 days after deletion by the hourly job `account.erase_deleted`. A remote account's posts go too, including those that local users bookmarked or replied to.
  A remote account that was marked deleted only because a fetch answered `410 Gone`, without its own signed `Delete`, is fetched once more first. A second `410` erases it. If its server serves it again, it comes back with its posts, and nothing is erased. Any other answer (`404`, or no answer) waits for a later run, and 30 days after the deletion the account is erased anyway.
  An account under a hold is not erased. Posts that a report or action points to stay until that record is removed. The account's URI and username and the action records remain.
  The names and descriptions that the account gave its voice chat rooms are emptied; the rooms stay.

### Exporting for disclosure requests

For a disclosure request (GDPR Article 15, Japan's Act on the Protection of Personal Information Article 33), respond by exporting all of an account's moderation records as JSON.

```sh
my admin account export-moderation @alice > alice-moderation.json
```

- The export contains the actions against the account (including private notes, lifting, appeals and reviews), the reports about the account (comment, target posts, rules cited, moderators' notes, assignments, resolutions, reopenings), the reports the account made (only whether each is open or resolved), and the audit logs of those.
- The identity of reporters (the reporting account, and the URI and the origin server of a received report) is not exported. Before you hand the export over, check that a report's comment does not say anything that identifies the reporter.
- A moderator is exported by user ID. Place a hold first so that records are not removed while you handle the request.
