Getting started
Overview
What Limenia does for your app, how a report becomes a decision, and the hard rules of every integration.
Limenia is a moderation service for apps under the EU Digital Services Act (DSA). Your app backend sends user reports (and, optionally, content for review before publication) to the Limenia REST API, moderators decide in the Limenia dashboard, and Limenia sends every decision with a ready-made statement of reasons back to your backend as a signed webhook. Your content and your users stay in your app; Limenia keeps only what you send with a report.
| Base URL | https://app.limenia.eu/v1 |
| API version | 0.33.0 |
| OpenAPI specification | https://limenia.eu/openapi/v1.yaml (the /v1 operations, webhook events under x-webhooks) |
| All pages in one file (for coding agents) | https://limenia.eu/docs/integration.md |
| All pages and the spec in one file | https://limenia.eu/llms-full.txt |
| Example backends (Apache 2.0) | https://github.com/DL3KB/limenia-examples |
Flutter package limenia (API and widgets) |
https://pub.dev/packages/limenia |
Flutter device plugin limenia_device (optional) |
https://pub.dev/packages/limenia_device |
| Source of both Flutter packages (Apache 2.0) | https://github.com/DL3KB/limenia-flutter |
This documentation is written so that a coding agent (Claude Code, Cursor, Copilot) can read it once and integrate an app correctly. Start with the Quickstart, pick your stack in Choose your path, and finish with Testing and the go-live checklist.
Hard rules
Important: Follow these in every integration. They override anything else in this documentation.
- The API key lives in the backend only. Read it from the environment variable
LIMENIA_API_KEY(or the platform’s secret store that fills it). Never put it in the mobile or web app, in a config file shipped with the app, in remote config, in source control or in logs. Never ask the user to paste the key into the chat: ask them to set the environment variable or secret themselves and refer to$LIMENIA_API_KEY. The same holds for the identifier keyLIMENIA_IDENTIFIER_KEYof ban evasion across apps. - The app talks to its own backend only, never to Limenia. In Flutter, implement
LimeniaTransportof the Flutter packagelimeniaso that it calls your backend. Your backend calls Limenia. - The backend sets the people.
reporter.externalUserIdof a report,appellant.externalUserIdof a complaint, the author (subject) of a review request and theexternalUserIdof a device check come from your backend’s own login, never from the request body of the app. Use a stable internal user ID, never an e-mail address. - Verify every webhook. The webhook secret is in
LIMENIA_WEBHOOK_SECRET. Check the headerLimenia-Signature: t=<unix seconds>,v1=<hex>wherev1 = hex(HMAC-SHA256(secret, t + "." + rawBody)), computed over the raw request body exactly as received (never re-serialized JSON), compared in constant time, and reject atmore than 300 seconds away from your clock. Answer 401 on a failed check. Details in Webhooks. - No content and no personal data in logs. Log IDs (event, decision, report, user IDs) and error codes, never report texts, statements of reasons, names, e-mail addresses, IP addresses, device tokens or media URLs.
- Use idempotency keys as the API defines them.
POST /v1/reports,POST /v1/appeals,POST /v1/reviewsandPOST /v1/signalsrequire the headerIdempotency-Key(1 to 200 characters). Create one key per logical request (e.g.report-<your report ID>), store it with the request, and send the same key with the same body on every retry. Never reuse a key for a different body (409idempotency_key_reused).POST /v1/devices/checktakes no key and is never retried with the same token. - Respect rate limits and
Retry-After. Retry network errors, timeouts, 429 and 5xx with exponential backoff (1, 2, 4, 8 s), and on 429 or 503 wait at least the seconds inRetry-After. Never retry other 4xx answers unchanged.
How it works
User reports something in your app → your app sends it to your backend with your own login → your backend calls POST /v1/reports with the API key → a moderator decides in the Limenia dashboard → Limenia sends the signed webhook decision.created to your backend (and, with optional connectors, acts in Firebase Authentication, Supabase Auth or RevenueCat) → your backend applies the action (remove content, suspend user, …) and shows the statement of reasons.
- Your backend sends each report with a snapshot of the content to
POST /v1/reports(Reports). - Limenia bundles reports on the same content into one case while it is open or in review. Reports without content are bundled per reported user. Media are downloaded in the background.
- A moderator decides. Every decision has exactly one action and a statement of reasons (Art. 17 DSA).
- Limenia sends
decision.createdto your webhook (Webhook events). Optional connectors also disable accounts in Firebase Authentication or Supabase Auth and adjust purchases in RevenueCat. - When a temporary suspension ends, Limenia sends
subject.status_changed. - If the case had reports of users, Limenia also sends
reports.resolvedso you can inform the reporters (Art. 16(5) DSA). - Affected users and reporters can complain against a decision for six months through your backend (
POST /v1/appeals, Art. 20 DSA, see Complaints). The result comes asappeal.resolved. - Content that should only appear after a check goes to
POST /v1/reviewsbefore you publish it (Pre-moderation reviews). The result comes asreview.decided. - With the device connector, your backend checks the device at registration and login (
POST /v1/devices/check, see Device checks). - Signals (
POST /v1/signals, see Signals) are observations about users that the tenant’s rules can turn into cases.
The terms used here (tenant, app, case, decision, user file, policy, rule and so on) are explained in Concepts.
What Limenia stores
| Limenia stores | Stays in your app |
|---|---|
| Snapshot of the reported content: text, context, link, copies of media | The content itself and everything else |
| Reports: reason, free text, source; the reporter only as a hash | Who reported what |
| Reported users: your external user ID, display name, sanction status | Accounts, profiles, e-mail addresses |
| Cases, decisions, statements of reasons, audit log, delivery log | Carrying out the actions (delete, block, notify) |
| Complaints, review requests with a copy of the submitted content | Publishing content, notifying people |
More in Data protection.
How this documentation is organised
| Section | What you find there |
|---|---|
| Getting started | This overview, the Quickstart, Concepts and Choose your path |
| Integration guides | One complete path per stack, from Flutter with Firebase to any other backend |
| API reference | API basics (keys, errors, limits, idempotency) and one page per group of /v1 operations |
| Webhooks | Receiving webhooks and every event with its payload |
| Connectors | Firebase, Supabase, RevenueCat, devices and store reviews |
| Compliance | DSA and data protection: what your app must do and what Limenia does |
| SDKs and tools | Packages, examples, the spec and llms.txt |
| Testing and go-live | Testing, go-live checklist, troubleshooting, FAQ and changelog |