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.

Shell
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.

JSON
{
  "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 own decision.created with appealId and replacesDecisionId. Apply the action only when that decision.created arrives. After a complaint against remove_content or restrict_content, restore carries restoreScope: "content" and does not touch the account; after a complaint against warn_user, suspend_user or ban_user it carries restoreScope: "account". If the new decision ends a ban or suspension, subject.status_changed comes as well.
  • Show statementText completely, 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 from appeal.resolved, fall back to GET /v1/appeals/{appealId}. Remember which appealId belongs to which user and return the status only to them.
  • Reporters: give every report an externalReportId or store the reportId; inform reporters on reports.resolved and offer a complaint until appealDeadline (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 reporterWarning with issuedAt: 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/reports answers 403 reporter_suspended with suspendedUntil in 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 trustedFlaggerId only for people who verifiably act for one (see Reports).