API reference
Complaints
POST /v1/appeals and GET /v1/appeals/{appealId} — complaints against decisions (Art. 20 DSA), reporters and misuse.
Affected users and reporters have a right to complain against a decision (internal complaint handling, Art. 20 DSA). In the API a complaint is an appeal.
POST /v1/appeals
A complaint against a decision (internal complaint handling, Art. 20 DSA). The affected user or a reporter complains in your app; your backend forwards it.
curl -sS -X POST "$LIMENIA_BASE_URL/v1/appeals" \
-H "Authorization: Bearer $LIMENIA_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: appeal-4b1d0e" \
-d '{"decisionId":"01K6G5H1TR8W4QZ3M0XCB7NDEC","appellant":{"type":"subject","externalUserId":"u_112"},"text":"The comment was a quote from a film, not an insult.","externalAppealId":"appeal_17"}'Response 201 Created: { "appealId": "01K6S1…", "status": "open" }. Store appealId with the person.
| Field | Required | Limits and meaning |
|---|---|---|
decisionId |
yes | ULID of the decision, from decision.created (decision.id) or reports.resolved (reports.decisionId) |
appellant.type |
yes | subject (the affected user) or reporter (a user who reported the case) |
appellant.externalUserId |
yes | 1 to 128 characters, from your login. For a reporter, the same ID that was sent as reporter.externalUserId (Limenia compares hashes). |
text |
yes | Reasons of the person, 1 to 5000 characters, plain text |
externalAppealId |
no | Your ID, 1 to 128 characters; comes back in appeal.resolved |
Who may complain:
appellant.type |
Against |
|---|---|
subject |
restricting decisions on them: remove_content, restrict_content, warn_user, suspend_user, ban_user, reject_submission |
reporter |
any decision on a case they reported, especially dismiss |
- Deadline: six calendar months after
decidedAt(if the target month is shorter, the last day of that month). - At most one open complaint per decision and person.
- Decisions without a case (actions from the user file, reviews) have no reporters; only the affected user can complain.
- A reporter whose reports are suspended gets 403
reporter_suspended; affected users can always complain.
Errors: 400 validation_failed; 401; 403 appeal_not_allowed, reporter_suspended, tenant_not_active; 404 not_found (unknown decision or another app); 409 appeal_window_closed, appeal_already_open, idempotency_key_reused; 429.
GET /v1/appeals/{appealId}
Status of a complaint; the fallback if appeal.resolved was missed. Return it only to the person who complained.
{
"id": "01K6S1…",
"externalAppealId": "appeal_17",
"decisionId": "01K6G5H1TR8W4QZ3M0XCB7NDEC",
"appellantType": "subject",
"status": "resolved",
"createdAt": "2026-10-02T08:00:00Z",
"outcome": "upheld",
"statementText": "Decision on your complaint\n\n…",
"resolvedAt": "2026-10-05T09:00:00.498765Z"
}status: open, in_review, resolved. outcome (upheld or changed), statementText and resolvedAt only when resolved; newDecisionId only with changed. Errors: 401, 404, 429.
Outcomes
Moderators handle complaints in their own queue; a human always decides. Results arrive as appeal.resolved (see Webhook events):
upheld: the decision stays; nothing changes in your app.changed: a new decision replaces the old one (newDecisionId) and arrives as its owndecision.createdwithappealIdandreplacesDecisionId. Apply the action only when thatdecision.createdarrives. After a complaint againstremove_contentorrestrict_content,restorecarriesrestoreScope: "content"and does not touch the account; after a complaint againstwarn_user,suspend_userorban_userit carriesrestoreScope: "account". If the new decision ends a ban or suspension,subject.status_changedcomes as well.- Show
statementTextcompletely, as plain text, to the person who complained (by e-mail if their account is blocked). It tells the person that a human decided and names the further options (out-of-court dispute settlement under Art. 21 DSA, courts).
In short
- Complaints: forward them with
POST /v1/appeals, show results fromappeal.resolved, fall back toGET /v1/appeals/{appealId}. Remember whichappealIdbelongs to which user and return the status only to them. - Reporters: give every report an
externalReportIdor store thereportId; inform reporters onreports.resolvedand offer a complaint untilappealDeadline(see Webhook events).
Reporters and misuse
Under Art. 23 DSA moderators may act against people who frequently send manifestly unfounded reports:
- Warning: a moderator warns the reporter. While the warning stands, the report response carries
reporterWarningwithissuedAt: show the reporter a notice. - Suspension: after a delivered warning, a moderator can suspend the reports of that person for up to 365 days. Then
POST /v1/reportsanswers 403reporter_suspendedwithsuspendedUntilin the problem, and nothing is stored. Show the end and do not retry. Complaints of that person as a reporter are refused the same way; complaints as an affected user are always possible. - Trusted flaggers (Art. 22 DSA): the tenant registers them in the dashboard; your backend sets
trustedFlaggerIdonly for people who verifiably act for one (see Reports).