Reports

File content reports on behalf of a user and read the moderated report queue from your server

The reports module lets a user report an entity or comment, and lets moderators read the queue of reports they’re responsible for.

Both functions act on behalf of a named user. Pass that user’s Sublay ID as userId — for createReport this is the reporter; for fetchModeratedReports it is the moderator whose queue is returned.

---

createReport

Files a report against an entity or comment on behalf of a user. If the same user has already reported the same target, the existing report is updated rather than duplicated.

const result = await sublay.reports.createReport({
  userId: "usr_abc123",
  targetType: "comment",
  targetId: "cmt_abc123",
  reason: "spam",
  details: "Posting the same link repeatedly.",
});

userId · string · required

The Sublay user ID filing the report (the reporter).

targetType · string · required

What is being reported: "entity" or "comment".

targetId · string · required

The Sublay ID of the entity or comment being reported.

reason · string · required

The reason for the report.

details · string

Optional free-text details about the report.

Returns — Promise<CreateReportResponse>

{
  message: string;
  code: "report/created" | "report/updated" | "report/already-reported";
}

---

fetchModeratedReports

Returns a paginated list of reports in the spaces the user moderates. Each report is aggregated across all users who reported the same target, and is populated with the target content and space.

const { data, pagination } = await sublay.reports.fetchModeratedReports({
  userId: "usr_mod123",
  status: "pending",
  targetType: "entity",
  sortBy: "new",
  page: 1,
  limit: 20,
});

userId · string · required

The Sublay user ID of the moderator whose queue to fetch.

spaceId · string

Filter to reports within a specific space.

targetType · string

Filter by target type: "entity" or "comment".

status · string

Filter by report status: "pending", "on-hold", "escalated", "dismissed", or "actioned".

sortBy · string

Sort order: "new" (most recent first) or "old" (oldest first).

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

spaceReputationId · string

Opts each reported target’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context — per-row from the space each report belongs to). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<Report>>

To act on a report (remove content, ban the author, or dismiss it), use handleEntityReport / handleCommentReport on the Space Moderation module.