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.

  1. 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 key LIMENIA_IDENTIFIER_KEY of ban evasion across apps.
  2. The app talks to its own backend only, never to Limenia. In Flutter, implement LimeniaTransport of the Flutter package limenia so that it calls your backend. Your backend calls Limenia.
  3. The backend sets the people. reporter.externalUserId of a report, appellant.externalUserId of a complaint, the author (subject) of a review request and the externalUserId of 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.
  4. Verify every webhook. The webhook secret is in LIMENIA_WEBHOOK_SECRET. Check the header Limenia-Signature: t=<unix seconds>,v1=<hex> where v1 = 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 a t more than 300 seconds away from your clock. Answer 401 on a failed check. Details in Webhooks.
  5. 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.
  6. Use idempotency keys as the API defines them. POST /v1/reports, POST /v1/appeals, POST /v1/reviews and POST /v1/signals require the header Idempotency-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 (409 idempotency_key_reused). POST /v1/devices/check takes no key and is never retried with the same token.
  7. 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 in Retry-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.

  1. Your backend sends each report with a snapshot of the content to POST /v1/reports (Reports).
  2. 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.
  3. A moderator decides. Every decision has exactly one action and a statement of reasons (Art. 17 DSA).
  4. Limenia sends decision.created to your webhook (Webhook events). Optional connectors also disable accounts in Firebase Authentication or Supabase Auth and adjust purchases in RevenueCat.
  5. When a temporary suspension ends, Limenia sends subject.status_changed.
  6. If the case had reports of users, Limenia also sends reports.resolved so you can inform the reporters (Art. 16(5) DSA).
  7. 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 as appeal.resolved.
  8. Content that should only appear after a check goes to POST /v1/reviews before you publish it (Pre-moderation reviews). The result comes as review.decided.
  9. With the device connector, your backend checks the device at registration and login (POST /v1/devices/check, see Device checks).
  10. 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