report_create

Flag content for review. By default the report is stored on the server, where moderators with review_reports can see it through report_list. Hosted servers can also forward reports to Rotur, the account service behind OriginChats.

Request

{
  "cmd": "report_create",
  "target_type": "message",
  "target_id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10",
  "channel": "general",
  "reason": "Posting phishing links"
}

Field	Type	Required	Description
target_type	string	Yes	What you are reporting: message, attachment, or user.
target_id	string	Yes	The message ID, attachment ID, or user ID. For users this is the account ID, not the username.
channel	string	For messages	The channel the message is in. Ignored for other target types.
reason	string	No	Why you are reporting it. Trimmed, at most 1000 characters. Defaults to "".
destination	string	No	owner to store the report on this server, or rotur to forward it to Rotur. Defaults to owner.

Only top-level channel messages can be reported. Messages inside threads, including forum posts, aren’t found.

Response

With destination: "owner", the server returns the stored report:

{
  "cmd": "report_create",
  "destination": "owner",
  "report": {
    "id": "5b1f3c1e-8d0a-4d6e-9f43-2a7c9e1b0d55",
    "reporter": "alice",
    "target_type": "message",
    "target_id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10",
    "reason": "Posting phishing links",
    "snapshot": {
      "channel": "general",
      "author": "mallory",
      "content": "Free nitro! https://example.test/claim",
      "attachments": [],
      "timestamp": 1727180412.531
    },
    "status": "open",
    "created_at": 1727180530.204,
    "resolved_by": null,
    "resolved_at": null
  }
}

Field	Meaning
id	Report ID (a UUID). Pass it to report_resolve.
reporter	Username of the person who reported.
target_type, target_id	What was reported, as sent.
reason	The reason text, trimmed.
snapshot	A copy of the reported content taken now, so moderators can see it even if it is later edited or deleted. Its shape depends on target_type; see below.
status	open, resolved, or dismissed. New reports are open.
created_at	Unix seconds.
resolved_by, resolved_at	Username and Unix seconds of the last review. null until reviewed.

The snapshot holds:

• message: channel, author (username), content (first 2000 characters), attachments (array of URLs), and timestamp.
• attachment: uploader (username), name (original file name), mime_type, and size in bytes.
• user: username.

With destination: "rotur", the report is sent to Rotur and not stored on this server:

{
  "cmd": "report_create",
  "destination": "rotur",
  "submitted": true
}

The server doesn’t notify moderators about new reports. They see them the next time they call report_list.

Permissions

Any joined member can report. For a message report you must be able to view the channel. A user in timeout gets a rate_limit frame instead.

Forwarding to Rotur works only when the server has a hosted configuration section and a ROTUR_TOKEN environment variable. It posts to hosted.report_url, or https://api.host.originchats.com/hooks/report when that isn’t set.

Errors

val	When
target_type: Required	target_type is missing. The same pattern applies to target_id.
target_type: Expected one of [message attachment user], received post	target_type isn’t one of the allowed values. The end of the message echoes what you sent.
target_id: Expected length at least 1	target_id is empty.
reason: Expected length at most 1000	reason is longer than 1000 characters.
destination: Expected one of [owner rotur], received mods	destination is not owner or rotur.
channel is required for message reports	target_type is message and channel is missing or empty.
The reported content could not be found	The target doesn’t exist, the attachment has expired, the message is in a thread, or you can’t view the message’s channel.
This server cannot forward reports to rotur	destination is rotur but the server isn’t hosted.
Could not submit the report, please try again later	Rotur rejected the report, didn’t answer within 10 seconds, or ROTUR_TOKEN isn’t set.
Report storage is unavailable	The report file can’t be read.
Unable to save report	The report couldn’t be written.

See also

• report_list
• report_resolve
• Moderation, reports & audit log