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

# Handle Report

> Resolve a report filed in a space: an entity, comment or chat message report

Resolves a report filed in a space, whatever was reported: an entity, a comment, or a message in the space's conversation. Requires the caller to be a moderator or admin of that space.

The request names only the report. The server reads what was reported from the report itself and acts on that content; `ban-user` bans that content's author. Which actions a report takes depends on what was reported:

| Report about | Actions |
| - | - |
| An entity | `remove-entity`, `ban-user`, `dismiss` |
| A comment | `remove-comment`, `ban-user`, `dismiss` |
| A chat message | `remove-message`, `ban-user`, `dismiss` |

> [!NOTE]
>
> **Requires the `moderation` bundle**, which holds reports: without it the request returns `403 database/tables-not-available`. A chat message report also needs the `chat` bundle, and `remove-entity` needs the `entities` bundle. See [Bundles](https://docs.sublay.io/v8/bundles.md).

## Path Parameters

**spaceId** `string` *required*

UUID of the space.

**reportId** `string` *required*

UUID of the report to resolve. It must be a report filed in this space.

## Body Parameters

**actions** `string[]` *required*

One or more actions to take, from the ones the report's type allows (see the table above). Must contain at least one value.

* `"remove-entity"`, `"remove-comment"`, `"remove-message"` — marks the reported content as removed via moderation
* `"ban-user"` — bans the author of the reported content from the space and the child spaces where they are an active member, and ends their membership of those spaces' chats, so they can no longer post to them, receive them or read their history (see [space conversations](https://docs.sublay.io/v8/data-models/conversation-member.md#space-conversations)). The same rules as [Ban Member](https://docs.sublay.io/v8/api-reference/spaces/membership/ban-member.md) apply, with the same errors: a moderator cannot ban a moderator or admin, only the space creator can ban an admin, and the last admin of a space cannot be banned. You can't ban yourself: when you are the author of the reported content, the request is refused (`400 report/cannot-ban-self`). A refused ban rolls back the whole request, including any removal in the same request, and the report stays pending. An author who is not a member of the space (for example, who left before the report was handled) is banned all the same: the ban is kept as a banned membership, so they can't join the space or its child spaces. If the author is already banned in the space, the ban is not repeated and the rest of the request still applies; it is still re-applied to their active memberships in child spaces, under the same rules. Requires `reason`.
* `"dismiss"` — dismisses the report without action. Cannot be combined with other actions.

**summary** `string` *required*

What the moderator did, up to 1000 characters. Stored as `actionTaken` on the report. Required for every report type, whatever the action; an empty or whitespace-only `summary` counts as missing (`400 report/missing-fields`).

**reason** `string`

Reason for the ban, up to 1000 characters, kept in the space's ban log. Required when `ban-user` is included in `actions`.

**actingUserId** `string`

Required with a service key: the user this request acts as. The request has exactly that user's permissions, so it is refused unless they are a moderator or admin of the space, and it is recorded as theirs. A user token always acts as its own user and must not send it (`400 space/acting-user-not-allowed`).

## Response

Returns `204 No Content` with no body.

## Error Responses

> [accordion] Invalid Id — 400
>
> Returned when `spaceId` or `reportId` isn't a valid UUID. Checked before sign-in, permissions and the endpoint's other checks.
>
> ```json theme={null}
> { "error": "Invalid space id: expected a UUID.", "code": "space/invalid-params" }
> ```

> [accordion] Missing token — 401
>
> No `Authorization` header was sent. The body is `text/plain` (`Unauthorized`), not JSON. An expired or invalid token returns `403` instead — see [Authentication](https://docs.sublay.io/v8/api-reference/authentication.md).

> [accordion] Missing Acting User — 400
>
> A service key sent no `actingUserId`.
>
> ```json theme={null}
> { "error": "A service key must send actingUserId: the user this request acts as.", "code": "space/missing-user-id" }
> ```

> [accordion] Invalid Acting User — 400
>
> `actingUserId` is not a user id.
>
> ```json theme={null}
> { "error": "actingUserId must be a user id.", "code": "space/invalid-body" }
> ```

> [accordion] Acting User Not Allowed — 400
>
> A user token sent `actingUserId`, even naming its own user. Only a service key names the user it acts as; a user token always acts as its own user.
>
> ```json theme={null}
> { "error": "actingUserId is only accepted with a service key. A user's own token always acts as that user.", "code": "space/acting-user-not-allowed" }
> ```

> [accordion] Wrong Location — 400
>
> `actingUserId` was sent in the query string. On this endpoint every field, `actingUserId` included, goes in the request body.
>
> ```json theme={null}
> { "error": "`actingUserId` goes in the request body on this endpoint.", "code": "space/wrong-location", "param": "actingUserId" }
> ```

> [accordion] Acting User Not Found — 404
>
> Returned when a service key names an `actingUserId` that isn't a user in this project.
>
> ```json theme={null}
> { "error": "No user with this actingUserId exists in this project.", "code": "space/user-not-found" }
> ```

> [accordion] Unsupported Parameter — 400
>
> The request named the reported content or its author. The server reads both from the report, so `entityId`, `commentId`, `messageId` and `userId` are refused. `param` names the field:
>
> ```json theme={null}
> {
>   "error": "`entityId` isn't supported in v8: the report's target is read from the report.",
>   "code": "report/unsupported-param",
>   "param": "entityId"
> }
> ```
>
> ```json theme={null}
> {
>   "error": "`userId` isn't supported in v8: `ban-user` bans the author of the reported content, read from the report.",
>   "code": "report/unsupported-param",
>   "param": "userId"
> }
> ```

> [accordion] Space Not Found — 404
>
> No space with this id exists in the project.
>
> ```json theme={null}
> { "error": "Space not found", "code": "space/not-found" }
> ```

> [accordion] Not a Moderator — 403
>
> The caller (or the user named by `actingUserId`) is not a moderator or admin of the space.
>
> ```json theme={null}
> { "error": "Moderator access required", "code": "space/moderator-required" }
> ```

> [accordion] Tables Not Available — 403
>
> A bundle the request needs isn't installed: `moderation` for any report, `chat` for a chat message report, `entities` for `remove-entity`. While the bundle is still being installed, the response is `503 database/tables-provisioning` instead.
>
> ```json theme={null}
> {
>   "code": "database/tables-not-available",
>   "missingTables": ["Reports"],
>   "dashboardUrl": "https://<dashboard>/<projectId>/database"
> }
> ```
>
> `remove-entity` on a project without the `entities` bundle:
>
> ```json theme={null}
> { "error": "Entities bundle is not available for this project", "code": "database/tables-not-available" }
> ```

> [accordion] Invalid Body — 400
>
> The body failed validation, such as an unknown action, an empty `actions` array, a `summary` or `reason` over 1000 characters, or a field of the wrong type. `error` describes the problem.
>
> ```json theme={null}
> { "error": "...", "code": "report/invalid-body" }
> ```

> [accordion] Report Not Found — 404
>
> No report with this id is in this space: the id names nothing, names a report in another space, or names a report a space moderator doesn't handle (a user report). All answer the same way.
>
> ```json theme={null}
> { "error": "Report not found", "code": "report/not-found" }
> ```

> [accordion] Invalid Actions — 400
>
> An action doesn't fit what was reported. The message lists the actions this report takes and the ones that were refused:
>
> ```json theme={null}
> { "error": "An entity report takes the actions `remove-entity`, `ban-user`, `dismiss`. Not allowed: `remove-comment`.", "code": "report/invalid-actions" }
> ```
>
> Also returned when `dismiss` is combined with another action (on a chat message report the message ends with a period):
>
> ```json theme={null}
> { "error": "Cannot combine 'dismiss' with other actions", "code": "report/invalid-actions" }
> ```

> [accordion] Missing Required Fields — 400
>
> The request has no `summary` (or only whitespace), on any report type. Nothing is changed: the report stays pending and no removal or ban in the same request is applied. With `dismiss`:
>
> ```json theme={null}
> { "error": "Summary is required for dismissing a report", "code": "report/missing-fields" }
> ```
>
> With any other action:
>
> ```json theme={null}
> { "error": "Summary is required", "code": "report/missing-fields" }
> ```
>
> `ban-user` was sent without `reason`:
>
> ```json theme={null}
> { "error": "reason is required for banning a user", "code": "report/missing-fields" }
> ```

> [accordion] Content Not Found — 404
>
> The reported content no longer exists, or isn't in this space. The code names the content type:
>
> ```json theme={null}
> { "error": "Entity not found", "code": "report/entity-not-found" }
> ```
>
> ```json theme={null}
> { "error": "Entity does not belong to this space", "code": "report/entity-not-in-space" }
> ```
>
> ```json theme={null}
> { "error": "Comment not found", "code": "report/comment-not-found" }
> ```
>
> ```json theme={null}
> { "error": "Comment does not belong to this space", "code": "report/comment-not-in-space" }
> ```
>
> ```json theme={null}
> { "error": "Message not found.", "code": "chat/message-not-found" }
> ```

> [accordion] No Author — 400
>
> `ban-user` was requested, but the reported content has no author to ban (for example, its author deleted their account).
>
> ```json theme={null}
> { "error": "The reported content has no author to ban.", "code": "report/no-author" }
> ```

> [accordion] Cannot Ban Self — 400
>
> `ban-user` would ban the moderator handling the report: they are the author of the reported content. Nothing is changed: the report stays pending and no removal in the same request is applied.
>
> ```json theme={null}
> { "error": "`ban-user` would ban you: you're the author of the reported content. Dismiss the report or remove the content instead.", "code": "report/cannot-ban-self" }
> ```

> [accordion] User Not Found — 404
>
> The author of the reported content isn't a user in this project. On a chat message report the message is `"User not found."`.
>
> ```json theme={null}
> { "error": "User not found in this project", "code": "report/user-not-found" }
> ```

> [accordion] Ban Refused — 400 / 403
>
> `ban-user` broke one of the [Ban Member](https://docs.sublay.io/v8/api-reference/spaces/membership/ban-member.md) rules, in this space or in a child space the ban reaches. `spaceId` names that space.
>
> ```json theme={null}
> { "error": "Moderators can only ban regular members.", "code": "space/insufficient-permissions", "spaceId": "…" }
> ```
>
> ```json theme={null}
> { "error": "Only the space creator can ban admins.", "code": "space/creator-required", "spaceId": "…" }
> ```
>
> ```json theme={null}
> { "error": "Cannot ban the last admin. Promote another member to admin first.", "code": "space/last-admin", "spaceId": "…" }
> ```

See also: [useHandleSpaceReport](https://docs.sublay.io/v8/hooks/reports/use-handle-space-report.md) · [Fetch Moderated Reports](https://docs.sublay.io/v8/api-reference/reports/fetch-moderated-reports.md)


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