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).
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"
}
JSONResponse 201 Created (also for a repeated request with the same key and body):
{ "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
subjectandcontentis required. With reported content, always send its author assubject; withoutsubjectmoderators cannot warn or suspend the user, withoutcontentthey cannot act on the content. - Cases and snapshots: reports on the same
externalContentIdof 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 anexternalContentId; 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_safetyandprotection_of_minorsmake the caseurgentimmediately, 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_evasionmeans the user circumvents a ban or suspension, e.g. with another account. Your app may send it (prioritynormal, no special handling). Limenia also creates such reports itself withsource: systemand priorityhigh, for example from the RevenueCat webhook. - Reserved:
cross_app_banis 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
GETwithout login, e.g. a signed URL valid for at least one hour.httpsonly, public addresses only; at most 3 redirects, each againhttpsand 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 (
unreachableorhttp_<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_exceededin 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.