> ## 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.

# Overview

> Content reporting and moderation tools at the project and space level

## Overview

Sublay provides a two-tier moderation system:

1. **Project-level moderation** — Users with project-level admin permissions can moderate any content across the entire project, regardless of which space it belongs to. This is typically used by the platform owner or trust-and-safety team.

2. **Space-level moderation** — Users with `admin` or `moderator` roles within a specific space can moderate content in that space only. Their capabilities are scoped to their space — they cannot view or act on reports from other spaces.

Both tiers share the same reporting flow. The difference is in who can act on reports and what scope they have access to.

Beyond acting on individual pieces of content, moderators can also **[suspend a user](/sdk/moderation/suspensions)** — an enforced, platform-wide timeout that blocks all participation writes while leaving reads, sign-in, and account self-management open.

<Note>
  **Requires the `moderation` bundle.** Reports, suspensions, and **user blocking** are only available when the `moderation` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

## Blocking

Beyond moderator-driven reporting and suspensions, the moderation bundle also provides **end-user blocking** — a user-to-user safety primitive. Any user can block any other user (no prior interaction required), and Sublay reliably severs interaction between them across every relevant surface.

Blocking is **not a moderator action** — it is exposed to your app's end users, alongside follows and connections, through the same SDK surfaces (React/React Native/Expo hooks, the node SDK, and the js SDK). Sublay ships the *capability and enforcement*; your app builds the block button/menu UI. See the [`useBlockManager`](/sdk/relationships/use-block-manager) hook to wire up a block/unblock toggle.

<Note>
  Blocking ships with the moderation bundle because app stores check for **reporting, blocking, and moderation together** — it is the trust & safety package an app installs to be app-store compliant. A project without the moderation bundle has neither reporting nor blocking.
</Note>

### What a block does

When user A blocks user B, the effects are **mutual** (both directions) unless noted, and the block is **silent** — B is never notified and can never tell they've been blocked (see [Non-disclosure](#non-disclosure) below).

| Surface                         | Effect of a block                                                                                                                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Follows**                     | Any existing follow in either direction is removed immediately. Neither can follow the other going forward.                                                                                                                                                                                |
| **Connections**                 | Any existing connection is removed and any pending request in either direction is cancelled. Neither can send a new request to the other.                                                                                                                                                  |
| **Direct messages (1:1)**       | Neither can start a new 1:1 conversation with the other. An existing 1:1 is frozen — history is retained and remains readable, but no new messages, edits, reactions, or deletes go through in either direction.                                                                           |
| **Group / space conversations** | Untouched. Both remain members of any shared group/space conversation and continue to see each other's messages there.                                                                                                                                                                     |
| **Content interaction**         | Neither can comment on, reply to, quote, or react to the other's posts or comments.                                                                                                                                                                                                        |
| **Content lists**               | Posts and comments authored by a block-edged user are hidden from the other's feeds and threads by default. An app may opt in to re-show **only** content the viewer themselves blocked (see [content-list opt-in](#content-list-opt-in)).                                                 |
| **Mentions**                    | Neither can mention the other; a mention does not notify or resolve to the blocked user. Pre-existing mentions are left in place but stop notifying.                                                                                                                                       |
| **Notifications**               | No notifications flow between the two users in either direction, for any reason.                                                                                                                                                                                                           |
| **Discovery**                   | Each user is excluded from the other's user suggestions, search results, interest matches, and follower/following/connection lists (and their counts).                                                                                                                                     |
| **Profile (asymmetric)**        | The **blocked** user can no longer view the **blocker's** profile — it presents as not found. The blocker retains access to the blocked user's profile and manages the block from their block list. This is the one asymmetric surface, so the blocker always keeps a way back to unblock. |

Unblocking lifts the barrier immediately but **restores nothing** — removed follows and connections stay gone and must be re-established from scratch; a frozen 1:1 conversation simply becomes usable again.

### Content-list opt-in

Post and comment list endpoints (and their SDK equivalents) accept a `blockedFilter` parameter. It defaults to `"exclude"` (hide block-edged authors). Setting it to `"include-outbound-blocked"` re-includes content authored **only** by users the viewer themselves blocked — their own "view anyway" affordance. It can **never** surface content from users who blocked the viewer, and interaction remains blocked regardless of whether the content is shown. See [Fetch Many Entities](/api-reference/entities/fetch-many-entities) and [Fetch Many Comments](/api-reference/comments/fetch-many-comments).

### Non-disclosure

A block is invisible to the blocked user. There is no notification, no "you have been blocked" state, and no distinguishable error — a blocked interaction fails exactly like ordinary unavailability (user/content not found or unavailable), never revealing that a block exists, who set it, or in which direction it runs. The block-status read is **outbound-only**: a user can only ever learn whether *they* block someone, never whether someone blocks *them*. A user's block list is private to that user.

### Block SDK surfaces

* **React / React Native / Expo hooks:** [`useBlockManager`](/hooks/blocks/use-block-manager), [`useBlockUser`](/hooks/blocks/use-block-user), [`useUnblockUser`](/hooks/blocks/use-unblock-user), [`useFetchBlockStatus`](/hooks/blocks/use-fetch-block-status), [`useFetchBlockedUsers`](/hooks/blocks/use-fetch-blocked-users).
* **Node SDK** (act-on-behalf via `actingUserId`): `createBlock`, `deleteBlock`, `fetchBlockStatus`, `fetchBlockedUsers` on the [`users`](/v7/node-sdk/users) module.
* **JS SDK** (token-derived actor): `createBlock`, `deleteBlock`, `fetchBlockStatus`, `fetchBlockedUsers` on the [`users`](/v7/js-sdk/users) module.
* **REST:** [Block User](/api-reference/users/blocks/block-user), [Unblock User](/api-reference/users/blocks/unblock-user), [Get Block Status](/api-reference/users/blocks/get-block-status), [Fetch Blocked Users](/api-reference/blocks/fetch-blocks).

## Reporting Flow

<Steps>
  <Step title="User submits a report">
    Call [`useCreateReport`](/hooks/reports/use-create-report) with the target ID and a reason key. If the target has already been reported, the user's report is appended to the existing report record.
  </Step>

  <Step title="Report is associated with a space">
    The server automatically determines which space the reported content belongs to. Reports with no space (content outside a space) are visible only to project-level moderators.
  </Step>

  <Step title="Moderator reviews pending reports">
    A moderator fetches pending reports with [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports):

    * **Project-level moderators** see all reports across the entire project.
    * **Space-level moderators** see only reports for content within their space.
  </Step>

  <Step title="Moderator takes action">
    Use [`useHandleSpaceEntityReport`](/hooks/reports/use-handle-space-entity-report) or [`useHandleSpaceCommentReport`](/hooks/reports/use-handle-space-comment-report) to remove content, ban the author, or dismiss the report. Space-level moderators can only act on content within their space.
  </Step>
</Steps>

## Moderation Tiers

### Project-Level Moderation

Project-level moderation is handled through the **Sublay Dashboard** — no code integration is required. Platform owners and trust-and-safety teams can log into the dashboard to review and act on reports across the entire project.

* Managed entirely from the Sublay Dashboard
* Access to all reports, regardless of space
* Can remove any entity or comment in the project
* Can ban any user from any space
* Suitable for platform-wide policy enforcement

### Space-Level Moderation

Space-level moderation must be **integrated in your application**. Users with an `admin` or `moderator` role within a specific space can be given a moderation UI inside your app using the hooks below. Their capabilities are scoped to that space — they cannot view or act on reports from other spaces.

* Built into your app using the provided hooks
* Can only view reports for content within their space
* Can remove entities, comments, and chat messages within their space
* Can ban users from their space only
* Cannot access reports or take action in other spaces

## Report Reasons

Reports must use one of these keys — the API rejects anything else with
`report/invalid-body`. Use `other` together with the free-text `details` field
for anything the list doesn't cover.

| Key                    | Label                                   |
| ---------------------- | --------------------------------------- |
| `spam`                 | It's spam                               |
| `inappropriateContent` | Contains inappropriate content          |
| `harassment`           | It's harassment or bullying             |
| `misinformation`       | Spreads false information               |
| `hateSpeech`           | Contains hate speech or symbols         |
| `violence`             | Promotes violence or dangerous behavior |
| `illegalActivity`      | Promotes illegal activity               |
| `selfHarm`             | Promotes self-harm or suicide           |
| `other`                | Other                                   |

Import reason keys from `@sublay/core`:

```ts theme={null}
import { reportReasons } from "@sublay/core";
// { spam: "It's spam", inappropriateContent: "Contains inappropriate content", ... }
```

## Hooks

The hooks below are used for **space-level moderation** integrated in your app. Project-level moderation does not require any hooks — it is handled through the Sublay Dashboard.

<CardGroup cols={2}>
  <Card title="useCreateReport" href="/hooks/reports/use-create-report">
    Submit a report against an entity, comment, or chat message.
  </Card>

  <Card title="useFetchModeratedReports" href="/hooks/reports/use-fetch-moderated-reports">
    Fetch pending reports for spaces the current user moderates.
  </Card>

  <Card title="useHandleSpaceEntityReport" href="/hooks/reports/use-handle-space-entity-report">
    Action an entity report as a space moderator.
  </Card>

  <Card title="useHandleSpaceCommentReport" href="/hooks/reports/use-handle-space-comment-report">
    Action a comment report as a space moderator.
  </Card>

  <Card title="useHandleSpaceChatReport" href="/hooks/reports/use-handle-space-chat-report">
    Action a chat message report as a space moderator.
  </Card>
</CardGroup>

## Related

* [Blocking](#blocking) — End-user user-to-user blocking (via [`useBlockManager`](/sdk/relationships/use-block-manager))
* [Suspensions](/sdk/moderation/suspensions) — Platform-wide user timeouts that block participation writes
* [Space Moderation](/sdk/spaces/moderation) — Direct moderation of entities and comments within a space (without the reporting flow)
* [Space Rules](/sdk/spaces/rules) — Define community rules that appear alongside moderation decisions