API Reference

List Reports

Overview

Fetch the tenant's moderation report queue — messages flagged by chat users — for the Platform moderation inbox.

Each row includes who reported it, the reason, current status, a snapshot of the reported message, and the message sender's live mute/ban state so moderators can triage and act without extra lookups.

When to use this endpoint?

Use List Reports when:

Opening Platform → Moderation to review pending or resolved reports.
Building a queue table that shows reporter, reason, message preview, and sender moderation state.
Refreshing the inbox after Resolve, Mute, or Ban so statuses and sender flags stay current.
Reading pagination to page through a large report backlog.

Part of the client Platform Moderation module. Chat users create reports via Messages → Report; this endpoint is for tenant admins reviewing that queue — not for end-user chat SDKs.

Response Data

data.list is an array of report objects. data.pagination describes the current page (defaults apply — this call takes no query parameters).

Report fields

Field	Description
_id	Report id — use with Resolve Reports.
messageId	Id of the reported message.
conversationId	Conversation that contains the message.
reportedBy	Reporter summary: `_id`, `name`, `email`.
reason	Free-text reason supplied when the message was reported.
status	Queue status such as `pending`, `resolved`, or `dismissed`.
resolution / resolutionNote / resolvedAt	How the report was closed, optional note, and when — `null` while still pending.
message	Snapshot of the reported message (`content`, `type`, `sender`, timestamps). May be absent if the message was already deleted.
messageSender	Author of the reported message, including live `mutedUntil` and `isBanned`.
createdAt / updatedAt	ISO timestamps for the report.

pagination

Field	Description
currentPage	Current 1-based page.
totalCount	Total reports matching the queue.
pageSize	Items returned per page.
hasNextPage / hasPreviousPage	Whether adjacent pages are available.

GET{baseUrl}/api/{apiVersion}/client/moderation/reports

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

This endpoint takes no path or query parameters. Pagination metadata is still returned using server defaults (for example page size 10).

Success Response (HTTP 200 OK)

On success, the API returns a paginated list of reports with nested message and messageSender details.

json

{
  "success": true,
  "message": "Reports fetched successfully",
  "data": {
    "list": [
      {
        "_id": "6a589c2dc43829ebc51a80ee",
        "messageId": "6a589c2dbaf5974af7cbca85",
        "conversationId": "6a589b96cfa34ab66e35b2ac",
        "reportedBy": {
          "_id": "6a589b96cfa34ab66e35b2aa",
          "name": "Mod Test",
          "email": "mod-test-0716@example.com"
        },
        "reason": "Spam content",
        "status": "pending",
        "resolution": null,
        "resolutionNote": null,
        "resolvedAt": null,
        "createdAt": "2026-07-16T08:54:05.615Z",
        "updatedAt": "2026-07-16T08:54:05.615Z",
        "__v": 0,
        "message": {
          "_id": "6a589c2dbaf5974af7cbca85",
          "sender": "6a589b96cfa34ab66e35b2ab",
          "content": "spam spam spam buy now",
          "type": "text",
          "createdAt": "2026-07-16T08:54:05.438Z"
        },
        "messageSender": {
          "_id": "6a589b96cfa34ab66e35b2ab",
          "name": "Bad Actor",
          "email": "badactor@example.com",
          "mutedUntil": "2026-07-16T09:03:29.501Z",
          "isBanned": true
        }
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 1,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Common Errors

List fails when the token is missing/invalid or the caller is not a tenant admin.

HTTP 401 Unauthorized — No token

json

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

HTTP 403 Forbidden — Tenant admin required

json

{
  "success": false,
  "message": "Access denied: tenant admin privileges required",
  "data": null,
  "error": null
}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Moderation.
500 Internal Server Error	An unexpected error occurred while fetching reports.

Best Practices

Highlight status: "pending" rows so moderators clear the queue first.
Show messageSender.isBanned and mutedUntil badges before offering Mute / Ban again.
If messageis missing, render a "message deleted" placeholder — the report row itself may still need Resolve.
After Resolve / Mute / Ban, refetch List Reports so the inbox and sender state stay in sync.
Keep report reasons and message content restricted to trusted Platform admins.

Reports loaded

Use each report's _id with Resolve Reports, and the sender's _id with Mute/Unmute User or Ban/Unban User.

Field

Description

_id

Report id — use with Resolve Reports.

messageId

Id of the reported message.

conversationId

Conversation that contains the message.

reportedBy

Reporter summary: _id, name, email.

reason

Free-text reason supplied when the message was reported.

status

Queue status such as pending, resolved, or dismissed.

resolution / resolutionNote / resolvedAt

How the report was closed, optional note, and when — null while still pending.

message

Snapshot of the reported message (content, type, sender, timestamps). May be absent if the message was already deleted.

messageSender

Author of the reported message, including live mutedUntil and isBanned.

createdAt / updatedAt

ISO timestamps for the report.

Field

Description

currentPage

Current 1-based page.

totalCount

Total reports matching the queue.

pageSize

Items returned per page.

hasNextPage / hasPreviousPage

Whether adjacent pages are available.

Header

Value

Description

Authorization

Bearer <access_token>

Client Access Token with tenant admin privileges (Platform panel).

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

{ "success": true, "message": "Reports fetched successfully", "data": { "list": [ { "_id": "6a589c2dc43829ebc51a80ee", "messageId": "6a589c2dbaf5974af7cbca85", "conversationId": "6a589b96cfa34ab66e35b2ac", "reportedBy": { "_id": "6a589b96cfa34ab66e35b2aa", "name": "Mod Test", "email": "mod-test-0716@example.com" }, "reason": "Spam content", "status": "pending", "resolution": null, "resolutionNote": null, "resolvedAt": null, "createdAt": "2026-07-16T08:54:05.615Z", "updatedAt": "2026-07-16T08:54:05.615Z", "__v": 0, "message": { "_id": "6a589c2dbaf5974af7cbca85", "sender": "6a589b96cfa34ab66e35b2ab", "content": "spam spam spam buy now", "type": "text", "createdAt": "2026-07-16T08:54:05.438Z" }, "messageSender": { "_id": "6a589b96cfa34ab66e35b2ab", "name": "Bad Actor", "email": "badactor@example.com", "mutedUntil": "2026-07-16T09:03:29.501Z", "isBanned": true } } ], "pagination": { "currentPage": 1, "totalCount": 1, "hasNextPage": false, "hasPreviousPage": false, "pageSize": 10 } }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Tenant admin privileges required for Platform Moderation.

500 Internal Server Error

An unexpected error occurred while fetching reports.