Moderation API #
JSON read and mutation surface for the moderation dashboard. Every endpoint is
server-gated twice: the router wraps it in RequireModerator / RequireAdmin
/ RequirePermission, and the handler repeats the check, so no panel or
admin-only field is exposed to callers that lack the matching permission.
Conventions #
- Every
/api/*path answers with JSON.APIJSONMiddlewaresetsAccept: application/jsonon the way in and rewrites any non-JSON error body into the envelope. - Shared mutation handlers accept
application/jsonbodies or form-encoded bodies (readModerationParams) and always answer with the JSON action result. - Errors are
{"error": "...", "code": "..."}with a matching HTTP status.codeis one ofauthentication_required,permission_denied,invalid_request,not_found,internal_error,service_unavailable. - All timestamps are RFC 3339. Lists are always arrays (
[], nevernull). Anullpanel means the caller lacks the permission that guards it. - Request bodies for the mutation endpoints may be
application/x-www-form-urlencoded(as the dashboard sends them) or JSON with the same snake_case field names.
GET /api/moderation #
Handler: (*Handler).HandleAdminJSON. Required: authenticated moderator.
Query parameters:
| name | default | validation |
|---|---|---|
limit |
50 | 1–200 |
offset |
0 | >= 0 |
enrich_reports |
false |
true enables enrichment |
Pagination is applied to every list panel the caller may read. Invalid values
produce 400 invalid_request. Unless enrich_reports=true is passed, the
endpoint never makes network calls.
Response:
{
"viewer": {
"did": "did:plc:...",
"is_moderator": true,
"is_admin": false,
"can_hide": true,
"can_unhide": true,
"can_view_logs": false,
"can_view_reports": true,
"can_block": false,
"can_unblock": false,
"can_reset_autohide": false,
"can_dismiss_reports": true,
"can_manage_labels": false
},
"hidden": {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
"blocked": {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
"reports": {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
"activity": {"items": [], "total": null, "limit": 50, "offset": 0, "has_more": false},
"labels": {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
"stats": null,
"cache": null
}
Panel permissions:
| panel | visible when |
|---|---|
hidden |
can_hide or can_unhide |
blocked |
can_block or can_unblock |
reports |
can_view_reports (pending reports) |
activity |
can_view_logs |
labels |
can_manage_labels |
stats |
is_admin |
cache |
is_admin |
The pending-reports panel's Dismiss action is gated by
can_dismiss_reports; the server re-checks it on every mutation.
Panel pagination: total is the exact pre-pagination count for hidden,
blocked, reports and labels. The activity log is read newest-first from a
bounded window (offset + limit + 1, at most 1000 rows), so total is null
there and clients page with has_more.
Item shapes:
// hidden.items[]
{"at_uri": "at://...", "hidden_at": "...", "hidden_by": "did:plc:...",
"reason": "...", "auto_hidden": false}
// blocked.items[]
{"did": "did:plc:...", "blacklisted_at": "...", "blacklisted_by": "did:plc:...",
"reason": "..."}
// reports.items[]
{"id": "3k...", "subject_uri": "at://...", "subject_did": "did:plc:...",
"reporter_did": "did:plc:...", "owner_handle": "alice.example.com",
"reporter_handle": "bob.example.com", "preview": "Brew: longSteep",
"reason": "...", "created_at": "...", "status": "pending", "resolved_by": "",
"resolved_at": null}
// activity.items[]
{"id": "3k...", "action": "hide_record", "actor_did": "did:plc:...",
"target_uri": "at://...", "reason": "...", "details": {},
"timestamp": "...", "auto_mod": false}
// labels.items[]
{"id": "3k...", "entity_type": "user", "entity_id": "did:plc:...",
"label": "warned", "value": "", "created_at": "...", "created_by": "did:plc:...",
"expires_at": null, "expired": false}
// stats
{"known_users": 0, "registered_users": 0, "indexed_records": 0,
"total_likes": 0, "total_comments": 0, "firehose_connected": false,
"records_by_collection": {}, "backups": []}
// cache
{"witness_cache_available": false, "feed_index_available": false,
"backup_service_available": false,
"actions": {"export": false, "fetch_pds_records": true,
"refresh_handles": false, "rebuild": false, "purge": false}}
Reports are the stored pending reports. With enrich_reports=true, the endpoint
resolves owner and reporter handles plus a short content preview for the
visible page only, using the dashboard's existing enrichment path (AppView
profile lookups and the record's PDS, through the same resolver caches).
Enrichment has a hard two-second per-page budget; on timeout or lookup failure
the stored fields are still returned and owner_handle, reporter_handle or
preview stay empty. Default reads skip enrichment entirely, so pagination and
totals are unaffected either way.
stats.backups[]:
{"source": "feed", "healthy": true, "last_run": "...", "last_success": "...",
"last_failure": null, "last_error": "", "last_duration_ms": 0,
"last_size_bytes": 0, "retained_count": 0, "next_run": "..."}
Zero timestamps are emitted as null.
GET /api/moderation/stats #
Handler: (*Handler).HandleAdminStatsJSON. Required: admin.
Returns the same object as the stats panel (including backups), admin-only:
moderators receive 403 permission_denied.
Mutations #
Handlers: HandleHideRecord, HandleUnhideRecord, HandleBlockUser,
HandleUnblockUser, HandleResetAutoHide, HandleDismissReport,
HandleAddLabel, HandleRemoveLabel.
They are served only under /api/moderation/...; /_mod is the Solid dashboard
page, not a handler prefix.
JSON success body:
{"ok": true, "action": "hide_record", "target": "at://...", "message": "Record hidden from feed"}
action matches the audit-log action name. The body is the whole response:
there is no HTML fragment or redirect variant.
Request fields:
| endpoint | fields |
|---|---|
POST .../hide |
uri, reason |
POST .../unhide |
uri, reason |
POST .../block |
did, reason |
POST .../unblock |
did |
POST .../reset-autohide |
did |
POST .../dismiss-report |
id |
POST .../label/add |
entity_type (user/record), entity_id, label, value, expires (Go duration, e.g. 24h) |
POST .../label/remove |
entity_type, entity_id, label |
Missing or invalid fields produce 400 invalid_request with the validation
message; store failures produce 500 internal_error.
Operational endpoints #
These answer JSON, or an attachment, rather than the dashboard shape. The
mutations take did from the query string or from the body:
| route | required | response |
|---|---|---|
GET /api/moderation/export |
admin | witness-cache export, Content-Disposition: attachment |
GET /api/moderation/pds-records |
moderator | PDS export, Content-Disposition: attachment |
POST /api/moderation/purge |
admin | {"did","purged","purgedAt"} |
POST /api/moderation/rebuild |
admin | {"did","handle","rebuilt","rebuiltAt"} |
POST /api/moderation/refresh-handles |
admin | {"refreshed","failed","durationMs","finishedAt"} |
Their payload keys are camelCase for compatibility with existing operator
scripts. Validation failures are written as plain text by the handler and
rewritten into the error envelope by APIJSONMiddleware.
Router wiring #
| method | path | middleware + handler |
|---|---|---|
| GET | /api/moderation |
RequireModerator → HandleAdminJSON |
| GET | /api/moderation/stats |
RequireAdmin → HandleAdminStatsJSON |
| GET | /api/moderation/export |
RequireAdmin → HandleAdminExportDID |
| GET | /api/moderation/pds-records |
RequireModerator → HandleAdminFetchPDSRecords |
| POST | /api/moderation/purge |
RequireAdmin (+ CSRF) → HandleAdminPurgeDID |
| POST | /api/moderation/rebuild |
RequireAdmin (+ CSRF) → HandleAdminRebuildDID |
| POST | /api/moderation/refresh-handles |
RequireAdmin (+ CSRF) → HandleAdminRefreshHandles |
| POST | /api/moderation/hide |
RequirePermission(hide_record) → HandleHideRecord |
| POST | /api/moderation/unhide |
RequirePermission(unhide_record) → HandleUnhideRecord |
| POST | /api/moderation/block |
RequirePermission(blacklist_user) → HandleBlockUser |
| POST | /api/moderation/unblock |
RequirePermission(unblacklist_user) → HandleUnblockUser |
| POST | /api/moderation/reset-autohide |
RequirePermission(reset_autohide) → HandleResetAutoHide |
| POST | /api/moderation/dismiss-report |
RequirePermission(dismiss_report) → HandleDismissReport |
| POST | /api/moderation/label/add |
RequirePermission(manage_labels) → HandleAddLabel |
| POST | /api/moderation/label/remove |
RequirePermission(manage_labels) → HandleRemoveLabel |
The handlers repeat the authentication and permission checks internally, so a
missing middleware wrapper cannot leak the dashboard payload; the middleware is
still required for consistent 401/403 CSRF and rate-limit handling.