REST Admin Reports Checklist: Auditing Moderation Queues

By 4FreeForums Editors · Published October 31, 2026 · Sources linked below

Moderating community discussion requires dependable workflows to process incoming flags, inspect reported items, and apply administrative remedies. When managing a platform programmatically, platform operators can audit reports and coordinate enforcement through administrative endpoints. This checklist covers the core steps required to query, assign, update, and resolve pending reports according to the admin/reports API methods - Mastodon documentation, helping teams align their custom moderation scripts with established administrative standards.

1. Verify Scopes and Authentication Headers

Before issuing any requests to the admin endpoints, ensure your administrative credentials and authorization headers satisfy the necessary permission requirements:

• Bearer Token Authorization: Provide an Authorization request header formatted as Bearer <user_token> on every call. Missing or invalid headers will trigger an HTTP 403 Forbidden error with the message {"error": "This action is not allowed"}.
• Read Scope: Ensure the user token includes the admin:read:reports OAuth scope to inspect the queue or fetch single records.
• Write Scope: Confirm the token carries admin:write:reports before attempting to update classifications, assign tickets, resolve items, or reopen them.
• Administrative Permissions: Verify the authenticated account has the Manage Reports permission enabled in its assigned role.

For broader strategies on team oversight, see our Forum Moderation Guide for New Community Owners.

2. Query Pending Queues with Filtering Parameters

Auditing unhandled reports starts by retrieving the administrative queue using GET /api/v1/admin/reports. To organize incoming tickets efficiently, structure your queries with these parameters:

• Target Unresolved Flags: Use the unresolved boolean parameter (introduced in version 4.6.0 for API version 10) to isolate items waiting for review. You can combine unresolved with resolved to audit all historical reports simultaneously.
• Filter by Account: Isolate reports submitted by a specific user with account_id, or examine all complaints targeting a specific user via target_account_id.
• Set Request Limits: The endpoint defaults to returning 100 reports per page, with an allowed maximum limit of 200 reports.
• Handle Link Header Pagination: Report IDs are generally not exposed via standard API responses for manual offset calculation. Parse the HTTP Link header using the max_id, since_id, or min_id internal parameters to page forward and backward across older or newer records.

3. Inspect Single Report Objects and Context

When investigating a specific issue, call GET /api/v1/admin/reports/:id to inspect the full Admin::Report payload. Check the following elements within the response:

• Report Metadata: Verify the initial submission date (created_at), report category, and any reporter text stored in the comment field.
• Account Attributes: Check the filing account and the target_account, including their unique IDs, usernames, and email addresses.
• Attached Content: Review the arrays of attached statuses and rules to understand the context of the alleged misconduct.
• Execution Handoff: When an account-level penalty is required rather than closing the report passively, administrators can branch off to execute direct account enforcement via POST /api/v1/admin/accounts/:id/action.

To evaluate how these endpoints fit into a larger federated architecture, consult our Mastodon Moderation Tools: An At-a-Glance Profile.

4. Claim and Classify Queue Assignments

Prevent conflicting actions between multiple moderators by managing assignment states and correcting report categories:

• Assign to Self: Issue POST /api/v1/admin/reports/:id/assign_to_self to claim ownership of an item. A successful HTTP 200 response will populate the assigned_account field with your administrator details.
• Release Assignment: If a ticket needs to be released for another team member, send POST /api/v1/admin/reports/:id/unassign, which sets assigned_account back to null.
• Update Category Classification: Use PUT /api/v1/admin/reports/:id to update the category string to one of four recognized classifications: spam, legal, violation, or other.
• Map Exact Rule Violations: For reports classified under the violation category, pass an array of integer rule IDs in rule_ids[]. Rule IDs can be audited via GET /api/v1/instance/rules and GET /api/v1/instance.

5. Finalize the Audit: Resolve or Reopen

Once content has been assessed and any necessary administrative account actions have taken place, the report lifecycle must be closed out:

• Mark as Resolved: Dispatch POST /api/v1/admin/reports/:id/resolve to close the report with no further action pending. The object will reflect action_taken: true alongside the action_taken_at timestamp.
• Reopen When Necessary: If new context emerges regarding a closed case, dispatch POST /api/v1/admin/reports/:id/reopen. The server sets action_taken back to false and clears action_taken_at to null.

All endpoints described in this checklist adhere to the specifications in the admin/reports API methods reference documentation.

Sources

admin/reports API methods - Mastodon documentation

Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.