# 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. `APIJSONMiddleware` sets `Accept: application/json` on the way in and rewrites any non-JSON error body into the envelope. - Shared mutation handlers accept `application/json` bodies or form-encoded bodies (`readModerationParams`) and always answer with the JSON action result. - Errors are `{"error": "...", "code": "..."}` with a matching HTTP status. `code` is one of `authentication_required`, `permission_denied`, `invalid_request`, `not_found`, `internal_error`, `service_unavailable`. - All timestamps are RFC 3339. Lists are always arrays (`[]`, never `null`). A `null` panel 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: ```json { "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: ```json // 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[]`: ```json {"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: ```json {"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.