API reference

Reports

POST /v1/reports — report content or a user, with categories, media handling and how reports become cases.

POST /v1/reports

Report content or a user. Your backend calls it when a user reports something in your app (source: user) or when your app detected something itself (source: system).

Shell
curl -sS -X POST "$LIMENIA_BASE_URL/v1/reports" \
  -H "Authorization: Bearer $LIMENIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-7f3c9a" \
  --data @- <<'JSON'
{
  "source": "user",
  "reasonCategory": "harassment_hate",
  "reasonText": "Insults me in every comment",
  "goodFaith": true,
  "reporter": { "externalUserId": "u_829" },
  "subject": { "externalUserId": "u_112", "displayName": "maxi_99" },
  "content": {
    "externalContentId": "comment_5521",
    "contentType": "comment",
    "text": "Text of the reported comment",
    "media": [{ "url": "https://storage.example.com/signed/abc.jpg?sig=…" }],
    "externalUrl": "https://app.example.com/p/77#comment_5521",
    "createdAt": "2026-10-01T09:12:00Z",
    "context": { "postId": "p_77" }
  },
  "externalReportId": "rep_77"
}
JSON

Response 201 Created (also for a repeated request with the same key and body):

JSON
{ "reportId": "01K6…", "caseId": "01K6…", "caseCreated": true }

caseCreated is false when the report was added to an open case. While a moderator has warned the reporter, the response also carries "reporterWarning": { "issuedAt": "…" }: show the reporter a notice that further unfounded reports can lead to a suspension of their reports (see Complaints).

Fields

Field Required Limits and meaning
source yes user: a user reported it. system: your app detected it itself (the statement of reasons then says “own initiative”).
reasonCategory yes ^[a-z0-9_]{2,40}$, usually the code of a policy of the tenant (see Categories)
reasonText no Free text of the reporter, at most 2000 characters
goodFaith no true: the reporter confirmed in good faith that the report is accurate and complete (Art. 16(2)(d) DSA). Only with source: user; with system any value is rejected (validation_failed, invalid at /goodFaith). Absent or false counts as not confirmed. Set it only if the person confirmed it.
reporter.externalUserId no Reporter’s ID in your app, 1 to 128 characters; stored only as a hash. From your login. Omit with source: system; an empty string is rejected.
subject.externalUserId subject or content The reported user; for content its author. 1 to 128 characters, stable, not an e-mail address.
subject.displayName no At most 100 characters, trimmed; overwrites the stored name on every report
subject.identifiers no HMACs of the e-mail address and phone number of the reported user for ban evasion across apps (see Identifiers). Never causes an error.
content.externalContentId with content 1 to 256 characters, stable ID of the content; comes back in decisions
content.contentType with content ^[a-z0-9_]{1,40}$, your choice, e.g. comment, image, profile, message
content.text no At most 20 000 characters
content.media[].url no At most 10 entries, each at most 2048 characters, https only (see Media)
content.externalUrl no Link to the content in your app, at most 2048 characters; reference only, never fetched
content.createdAt no RFC 3339
content.context no JSON object, at most 4 KB serialized (too_large); IDs and technical details only. Keys of 1 to 128 bytes, no keys like __x__, no arrays in arrays, at most 10 levels (invalid)
externalReportId no Your report ID, 1 to 128 characters; comes back in reports.resolved
trustedFlaggerId no ULID of a trusted flagger of the tenant (Art. 22 DSA) the reporter acts for. Only with source: user. Unknown or inactive: validation_failed, unknown at /trustedFlaggerId. The case gets at least priority high. Set it only from your own records, never from the app.
  • At least one of subject and content is required. With reported content, always send its author as subject; without subject moderators cannot warn or suspend the user, without content they cannot act on the content.
  • Cases and snapshots: reports on the same externalContentId of an app go into the same case while it is open or in review; after a decision the next report opens a new case. Reports without content are bundled per reported user. The snapshot (text, media, context, link) is taken at the first report on an externalContentId; later reports do not change it. To have an edited content judged again, give each version its own ID, e.g. comment_5521@v2.

Errors

400 validation_failed, bad_request; 401; 403 tenant_not_active, reporter_suspended (with suspendedUntil; show the end and do not retry); 409 idempotency_key_reused; 429; 5xx. Reports are never refused because of the tenant’s plan or subscription. All codes are in API basics.

Categories

Limenia only checks the pattern of reasonCategory. Use the codes of the tenant’s policies (dashboard Policies), then the dashboard shows their titles. The default set created at setup:

Code Policy
spam Spam
harassment_hate Harassment and hate speech
violence Violence
sexual_content Sexual content
child_safety Protection of minors
fraud Fraud
copyright Copyright
privacy Privacy
self_harm Self-harm
other Other
  • Tenants can change and add policies, so agree on the codes with the tenant. The dashboard also understands the categories of the DSA transparency database (e.g. scams_and_fraud, protection_of_minors).
  • Child safety: the reason codes child_safety and protection_of_minors make the case urgent immediately, and Limenia stores no copy of the media for such reports (it keeps only the URL). If copies were already stored for earlier reports on the same content, they are deleted. Urgent cases can be filtered in the dashboard; there is no separate alert yet.
  • Ban evasion: ban_evasion means the user circumvents a ban or suspension, e.g. with another account. Your app may send it (priority normal, no special handling). Limenia also creates such reports itself with source: system and priority high, for example from the RevenueCat webhook.
  • Reserved: cross_app_ban is used by Limenia itself for ban evasion across apps (coming soon); do not send it.

Media

  • Limenia downloads media after answering, in the background. The result is visible only to moderators.
  • The URL must be fetchable with a plain GET without login, e.g. a signed URL valid for at least one hour. https only, public addresses only; at most 3 redirects, each again https and public.
  • Per attempt 10 s in total and at most 20 MB. Only HTTP 200 counts. A timeout, a connection error, 429 and 5xx are retried after 10 and 20 seconds; after the third attempt the medium fails (unreachable or http_<status>). Every other status fails at once.
  • The same URL within one content is downloaded once.
  • Each tenant has a quota of media downloads: about 300 per hour with bursts of up to 100. Media beyond it are not downloaded (quota_exceeded in the dashboard); the report itself is accepted as always. Need more: ask Limenia.
  • The type is detected from the content: JPEG, PNG, GIF, WebP, MP4, WebM and QuickTime (MOV). HEIC, HEIF and AVIF are not supported (send JPEG, PNG or WebP). Other types are discarded.
  • Limenia keeps a copy in private object storage and shows images blurred at first, only via short-lived signed links.

Trusted flaggers

A trusted flagger (Art. 22 DSA) is an organisation the tenant has registered in the dashboard. When a report comes from a person who verifiably acts for one, your backend sets trustedFlaggerId to its ID. The case gets at least priority high and a marker in the dashboard, and the statement of reasons says the decision follows a report by a trusted flagger (noticeSource: trusted_flagger). Set it only from your own records, never from the app. See also DSA.