Moderation reference

Exact names, types and behavior of the moderation APIs. For step-by-step guides, start at Moderation.

reports on a content typeCopy Anchor Link

defineContentType({ reports }) from @vitnode/core/content. Omitted or false registers nothing.

reports: true uses both defaults. It throws without publicApi, for an unknown option, for reports.enabled, and for a field that does not exist or cannot be snapshotted.

The server-side model can scope reports with createContentModel(definition, { moderationScope: { column, family } }), where column is a base-table column holding the resource id. A content type that reaches its container through a relation, such as a forum comment through its topic, has no such column, so its report permissions stay unscoped.

Generated moderator permissionsCopy Anchor Link

Added to the content type's permissionModule in the moderator catalog, unless the plugin declares that moderator module itself. All of them carry the target's scope family when it has one.

Content actions also need can_manage_reports, because they are recorded in the report.

Public write adds can_edit to the same module. In a container collection with publishing policies, can_edit and can_approve are scoped by the collection's family, whose id is the container definition id and whose resources are container ids and "{id}:tree" subtrees. See Container-scoped permissions. Generated entries merge with the report permissions; only a module the plugin declares itself in permissionStaff.moderator is left as declared.

Scoped grantsCopy Anchor Link

A stored grant is { plugin, module, permission, scope? }. scope is one of:

{ family: "example.category", mode: "all" }
{ family: "example.category", mode: "selected", ids: ["1", "2"] }

Declare a scoped permission with { permission, dependsOn?, scope: "family.id" } in permissionStaff.moderator. Admin permissions cannot be scoped. Resource ids match /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/.

PATCH /api/@vitnode/core/admin/staff/entry/moderator/{id} answers 400 with { error: "invalid_permissions", issues }. Each issue has a key and a type: missing_scope, empty_selection, invalid_resource, unknown_resource, unexpected_scope, wrong_family or dependency_scope. A grant wider than the caller's own permissions is 403.

GET /api/@vitnode/core/users/permissions returns the signed-in user's moderator grants, each with its scope.

defineModerationScopeCopy Anchor Link

From @vitnode/core/api/moderation. Register with buildApiPlugin({ moderation: { scopes } }).

An item is { id: string; label: string; context?: string[] }. The AdminCP reads them through GET /api/@vitnode/core/admin/staff/scope-resources/{family}?search=&cursor=, or ?ids=1,2 to label a saved selection, which also returns missing ids.

Custom report targetsCopy Anchor Link

Content Engine types register their target automatically. Anything else registers one with defineReportTarget and buildApiPlugin({ moderation: { reportTargets } }).

run executes inside the report's transaction and returns { changed, effects }. effects runs after the commit. When run throws, the transaction rolls back and no timeline entry is written.

Report UICopy Anchor Link

Public pages report a target with the components from @vitnode/core/tanstack/moderation. Both load their own messages (REPORT_NAMESPACES) and lazy-load the form, and both show a Sign in link instead of the form to guests. For a walkthrough, see Enable reports.

contentTargetCopy Anchor Link

contentTarget(pluginId, definition, id) from @vitnode/core/content returns the ContentTarget of one record: { pluginId, type, id }, where type is definition.id and id is the record id as a string. A custom report target uses the same shape with its own type.

ReportButtonCopy Anchor Link

A ghost button labelled Report that opens the dialog. Its accessible name is "Report typeLabel".

ReportDialogCopy Anchor Link

The same dialog, controlled by you. Use it for your own trigger, such as a menu item, or to share one dialog across a long list. It takes target, typeLabel, locale, requestedLocale and preview like ReportButton, plus open: boolean and onOpenChange(open: boolean).

import type { ContentTarget } from "@vitnode/core/content";

import { ReportDialog } from "@vitnode/core/tanstack/moderation";

const [reporting, setReporting] = useState<ContentTarget | null>(null);

{reporting ? (
  <ReportDialog
    onOpenChange={open => {
      if (!open) setReporting(null);
    }}
    open
    target={reporting}
    typeLabel={t("report_type")}
  />
) : null}

The dialog has three screens: pick a reason, add details, and Report sent. Picking a reason with a click, tap, Space or Enter moves on; arrow keys only move the selection. A failure shows a toast with a description: already reported (409 duplicate), no longer available (404), too many reports (429), session ended (401), reason just removed (400 reason_not_found, back to the reasons), missing details (400 details_required) and anything else.

Report lifecycleCopy Anchor Link

A report stores its reason's code. Admins manage the reasons in Report reasons; the four starter codes are spam, abusive, rule_violation and other, and only a reason with requiresDetails needs details. Every change except a note needs expectedVersion. A stale version answers 409 with { error: "conflict", current }, and taking a report someone else holds answers 409 already_claimed.

ModCP API routesCopy Anchor Link

All under /api/@vitnode/core/moderation, using the user session. A guest gets 401, a user without a moderator entry 403, and a report outside the moderator's scopes 404.

Report reasonsCopy Anchor Link

The AdminCP routes behind Report reasons, under /api/@vitnode/core/admin/report-reasons, using the AdminCP session. Each needs the matching report_reasons admin permission.

title and description are { languageCode, value }[]. title needs at least one value. Empty values are dropped, and a missing language falls back to the default language in the dialog. A new reason gets a generated code.

Approval routesCopy Anchor Link

Also under /api/@vitnode/core/moderation, for approvals. The queue routes need a moderator entry and show only submissions in containers where the moderator holds can_approve; anything else answers 404, so its existence is not revealed. Every response is Cache-Control: private, no-store.

The pending queue is oldest first; decided statuses are newest decision first. A list item has id, kind, status, contentTypeId, pluginId, itemId, title, author, reviewer, container ({ id, name, slug, path }), reason, createdAt and decidedAt.

A refused decision answers { error, message }:

Statuses are pending, approved, rejected, superseded (replaced by the author's newer proposal) and cancelled (the record was deleted first). The constants are CONTENT_SUBMISSION_STATUSES, CONTENT_SUBMISSION_KINDS and CONTENT_SUBMISSION_DECISION_CODES from @vitnode/core/content. Server code can decide one with decideContentSubmission(c, { decision, id, reason?, reviewerId }) from @vitnode/core/content/server, which throws ContentSubmissionDecisionError with the same code and status.

EventsCopy Anchor Link

Adding a note emits no event. Hiding through a report also emits the content type's own hidden or unhidden event. See Built-in events.

Snapshot formatCopy Anchor Link

Stored in core_moderation_reports.snapshot as JSON, version: 1:

The snapshot is read in one read-only transaction, so its fields and source describe the same state. The ModCP renders every snapshot with a generic viewer that needs no plugin code, and rich text goes through the same element allowlist as the public site.

LimitsCopy Anchor Link

File fields keep { id, name, mimeType, size, url } only. The file's bytes are never copied, so a file deleted later cannot be opened from the report.

DatabaseCopy Anchor Link

The migration 20261011193321_add_moderation_reports adds core_moderation_reports and core_moderation_report_events. Neither references the reported content, so deleting content keeps its reports. Reporter, assignee and resolver are ON DELETE SET NULL, so deleting an account keeps the evidence. The unique openKey column enforces one open report per reporter and target, even under concurrent submissions.

The migration 20261019161102_add_moderation_report_reasons adds core_moderation_report_reasons with a unique code, requiresDetails and position. Titles and descriptions live in core_languages_words. core_moderation_reports.reason holds the reason's code without a foreign key, so deleting a reason keeps its reports. db:prepare and db:migrate add the four starter reasons only while the table is empty.

Approvals live in core_content_submissions, one row per submission. Rows are never deleted with the content, author and reviewer are ON DELETE SET NULL, and a partial unique index allows one pending submission per record. Container policy overrides are stored in core_content_containers.policies.