> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sublay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

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

export const SpaceReputationParams = ({variant = "context", field = "path"}) => {
  const isUser = variant === "user";
  return <>
      <ParamField {...{
    [field]: "spaceReputation",
    type: "object"
  }}>
        Opt-in. Adds a <code>spaceReputation</code> number to each returned user,
        scoped to a single space. Requires the <code>reputation</code> bundle.
        The <code>reputation</code> total is always present regardless;{" "}
        <code>spaceReputation</code> is purely additive and only appears when you
        pass this object. <strong>This object is the primary form</strong> — it
        replaces the deprecated flat props below. See the{" "}
        <a href="/v8/data-models/reputation">Reputation data model</a> for the
        full contract.

        <Expandable title="spaceReputation">
          {isUser ? <ParamField name="spaceId" type="string | &quot;none&quot;" required>
              Which bucket to read. A space <strong><code>&lt;uuid&gt;</code></strong> reads that
              space's bucket; <strong><code>"none"</code></strong> reads the
              project-general (space-less) bucket.{" "}
              <strong><code>"context"</code> is rejected (400)</strong> on this
              endpoint — there is no space context to derive. The empty string
              and the legacy <code>general</code> / <code>null</code> aliases are
              also rejected. Missing buckets read as <code>0</code>.
            </ParamField> : <ParamField name="spaceId" type="string | &quot;none&quot; | &quot;context&quot;" required>
              Which bucket to read. One of: a space <strong><code>&lt;uuid&gt;</code></strong>{" "}
              (that space's bucket), <strong><code>"none"</code></strong> (the
              project-general, space-less bucket), or{" "}
              <strong><code>"context"</code></strong> (the space derived from the
              request context — resolved per-row on lists, or the single space on
              member/team/conversation surfaces). The empty string and the legacy{" "}
              <code>general</code> / <code>null</code> aliases are rejected (400).
              Missing buckets read as <code>0</code>.
            </ParamField>}
          <ParamField name="includeDescendants" type="boolean">
            Only honored when <code>spaceId</code> is an explicit space <code>&lt;uuid&gt;</code>.
            When <code>true</code>, <code>spaceReputation</code> is the{" "}
            <strong>subtree sum</strong> — the named space plus all of its
            descendant spaces (the root space's own bucket included). Ignored for{" "}
            <code>"none"</code>; not allowed with <code>"context"</code>.
          </ParamField>
        </Expandable>
      </ParamField>

      {isUser ? <ParamField {...{
    [field]: "spaceReputationId",
    type: "string",
    deprecated: true
  }}>
          <strong>Deprecated</strong> — use the <code>spaceReputation</code>{" "}
          object instead. The flat form of <code>spaceReputation.spaceId</code>.
          Still accepted (the object wins if both are passed); removal is a later
          major version. Accepts a space <code>&lt;uuid&gt;</code> or <code>"none"</code> only —{" "}
          <code>"context"</code> is rejected (400) on this endpoint.
        </ParamField> : <ParamField {...{
    [field]: "spaceReputationId",
    type: "string",
    deprecated: true
  }}>
          <strong>Deprecated</strong> — use the <code>spaceReputation</code>{" "}
          object instead. The flat form of <code>spaceReputation.spaceId</code>.
          Still accepted (the object wins if both are passed); removal is a later
          major version. Accepts a space <code>&lt;uuid&gt;</code>, <code>"none"</code>, or{" "}
          <code>"context"</code>.
        </ParamField>}

      <ParamField {...{
    [field]: "spaceReputationDescendants",
    type: "boolean",
    deprecated: true
  }}>
        <strong>Deprecated</strong> — use{" "}
        <code>spaceReputation.includeDescendants</code> instead. The flat form,
        only honored alongside an explicit <code>spaceReputationId</code> <code>&lt;uuid&gt;</code>.
      </ParamField>
    </>;
};

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

<Note>
  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.
</Note>

***

### createReport

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

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

<ParamField body="userId" type="string" required>
  The Sublay user ID filing the report (the reporter).
</ParamField>

<ParamField body="targetType" type="string" required>
  What is being reported: `"entity"`, `"comment"`, or `"message"`.
</ParamField>

<ParamField body="targetId" type="string" required>
  The Sublay ID of the entity, comment, or chat message being reported.
</ParamField>

<ParamField body="reason" type="ReportReason" required>
  One of `spam`, `inappropriateContent`, `harassment`, `misinformation`,
  `hateSpeech`, `violence`, `illegalActivity`, `selfHarm`, `other`. The API
  rejects anything else — use `other` plus `details` for the rest.
</ParamField>

<ParamField body="details" type="string">
  Optional free-text details about the report.
</ParamField>

<Note>
  Reporting a chat message uses `targetType: "message"` with the **message id**
  as `targetId` — the conversation is resolved server-side. Reports on space
  conversations reach space moderators; reports on DMs and group chats are
  project-level and appear only in the Sublay dashboard.
</Note>

**Returns** — `Promise<CreateReportResponse>`

```typescript theme={null}
{
  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.

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

<ParamField body="userId" type="string" required>
  The Sublay user ID of the moderator whose queue to fetch.
</ParamField>

<ParamField body="spaceId" type="string">
  Filter to reports within a specific space.
</ParamField>

<ParamField body="targetType" type="string">
  Filter by target type: `"entity"`, `"comment"`, or `"message"`. Message
  reports appear in this queue only for space conversations — DM and group
  reports are project-level and surface in the dashboard.
</ParamField>

<ParamField body="status" type="string">
  Filter by report status: `"pending"`, `"on-hold"`, `"escalated"`, `"dismissed"`, or `"actioned"`.
</ParamField>

<ParamField body="sortBy" type="string">
  Sort order: `"new"` (most recent first) or `"old"` (oldest first).
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

<SpaceReputationParams variant="context" field="body" />

**Returns** — `Promise<PaginatedResponse<Report>>`

<Note>
  To act on a report (remove content, ban the author, or dismiss it), use
  `handleEntityReport` / `handleCommentReport` on the
  [Space Moderation](/v8/node-sdk/spaces-moderation) module.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.