API reference
API basics
Base URL, API keys, versioning, idempotency, errors, rate limits, limits, pagination and timestamps of the /v1 API.
Base URL
The base URL is https://app.limenia.eu/v1. Every path starts with /v1. The API is for app backends only: it sends no CORS headers, so browsers cannot call it, and the API key must never reach a browser or mobile app anyway. Content type is application/json in both directions; errors are application/problem+json.
Authentication
Send the API key of the app in the Authorization header:
GET /v1/ping HTTP/1.1
Host: app.limenia.eu
Authorization: Bearer lm_live_...- The scheme is
Bearerwith a capital B, followed by one space. - The key determines tenant and app; Limenia never reads them from the body or the path. The only exception is the RevenueCat webhook receiver, which RevenueCat calls with its own header.
- A missing, malformed, unknown or revoked key answers 401
unauthenticated. Do not sign your app user out on this error: it is a problem of your backend’s configuration.
API keys
- An admin creates keys per app in the dashboard (tab Connection → API keys). An app can have several keys.
- Format:
lm_live_plus 43 Base62 characters. Keys created in early versions of Limenia start withlm_test_; they keep working and behave exactly the same. The prefix does not select a sandbox: every key writes to the real system. Use a separate test app for tests (see Testing). - The key is shown exactly once. Limenia stores only its SHA-256 hash and cannot show it again.
- Store it as
LIMENIA_API_KEYin your backend’s secret store, never in the app, in source control or in logs. - Rotation: create a new key, deploy it, then revoke the old one. A revoked key stops working within 30 seconds.
Check a key with GET /v1/ping:
curl -sS "$LIMENIA_BASE_URL/v1/ping" -H "Authorization: Bearer $LIMENIA_API_KEY"{ "tenantId": "01K6…", "appId": "01K6…", "appSlug": "photoapp", "tenantStatus": "active" }tenantStatus is onboarding, active or suspended. Reports are accepted only with active; GET /v1/ping works in every status. Use it at backend start or in a health check. Errors: 401, 429.
Versioning
- The path version
/v1stays stable. Changes within/v1are additive: new operations, new optional request fields, new response fields, new event types and new enum values. - Ignore unknown fields in responses and webhook payloads, and handle unknown enum values (for example a new
actionor eventtype) gracefully: acknowledge the webhook with 2xx and log it. - The version of the specification (currently in the header of the OpenAPI specification and on the Overview) follows semantic versioning. The changelog lists every change that affects the public API.
Requests
- Body at most 1 MiB. A larger body, invalid JSON or a wrong type (e.g. a date that is not RFC 3339) answers 400
bad_request. - Unknown fields in request bodies are ignored, so a typo in a field name is not reported. Field names are matched case-insensitively; always send them exactly as documented.
- Lengths count characters (Unicode code points), not bytes. Exception:
contextobjects are limited to 4 KB of serialized JSON. - URLs (media,
externalUrl, webhook) at most 2048 characters. - Timestamps are RFC 3339. Limenia answers in UTC with up to 6 fractional digits.
- IDs of Limenia (
reportId,caseId,decisionId,appealId,reviewId,checkId) are ULIDs: 26 characters, the first0to7. Webhook event IDs areevt_plus a ULID. - External IDs (
externalUserId,externalContentId,externalReportIdand so on) are yours and scoped per app. Use stable, pseudonymous IDs, never e-mail addresses. Encode them in paths (encodeURIComponent). - Timeouts: the first request after a pause can be slower. Use a client timeout of about 30 s.
Idempotency
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. - Same key and same body (compared by field values, not bytes): Limenia returns the original response with the original status and creates nothing.
- Same key, different body: 409
idempotency_key_reused. Never reuse a key for a different request. - Keys are kept per app for 24 hours, separately for reports, complaints, reviews and signals. After 24 hours the same key creates a new resource, so resend failed requests within 24 hours.
- A key is stored only on success. After a 400 you may send the corrected body with the same key.
- Without the header: 400
validation_failedwith a field error atIdempotency-Key. POST /v1/devices/checktakes no key: never retry it with the same token, get a new token instead.
Retries
- Retry network errors, timeouts, 429 and 5xx with exponential backoff (1, 2, 4, 8 s) and the same key and body.
- On 429 wait at least the seconds in
Retry-After. If a 503 carriesRetry-After, respect it as well. - Never retry other 4xx answers unchanged: fix the request.
- If it keeps failing, put the request in your own queue and resend it within 24 hours, so the idempotency key still deduplicates.
Rate limits
- 10 requests per second per API key, with bursts up to 50, for every operation with an API key (including
GEToperations and repeated requests). - A request with up to 100 signals counts once, so batch signals.
- Over the limit: 429
rate_limitedwithRetry-Afterin seconds. There are no rate limit headers on successful answers. - Invalid keys: a key that does not exist or was revoked is answered 401. Many requests with different invalid keys from one address are answered 429
rate_limitedwithRetry-Afterfor a while; keys in use are not affected. - Need more: ask Limenia for more keys or a higher limit.
Errors
Errors are application/problem+json (RFC 9457) with a machine-readable code:
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "The request contains invalid fields.",
"code": "validation_failed",
"errors": [{ "field": "/content/media/0/url", "code": "invalid", "message": "must be an https URL" }]
}- Branch on
statusandcode, never ontitle,detailormessage; those are for people and may change.detailcan be missing. errors[]lists field errors:fieldis a JSON pointer into the body (/content/media/0/url), a header name (Idempotency-Key) or a path parameter (externalUserId);codeisrequired,invalid,too_long,too_many,too_large,unknown,not_allowedortoo_many_values(a header sent twice);messageis an optional hint.reporter_suspendedaddssuspendedUntil.
| Status | code |
Meaning | Retry? |
|---|---|---|---|
| 400 | validation_failed |
Field errors in errors |
no, fix the body |
| 400 | bad_request |
Not valid JSON, wrong type (e.g. a date that is not RFC 3339) or body over 1 MiB | no |
| 400 | review_type_unknown |
POST /v1/reviews: the type is unknown or inactive |
no |
| 400 | signal_type_unknown |
POST /v1/signals: a type is unknown, inactive or a system type |
no |
| 400 | invalid_device_token |
POST /v1/devices/check: the provider rejected the token |
no, get a new token |
| 401 | unauthenticated |
Key missing, unknown, malformed or revoked | no (fix the key; do not sign your app user out) |
| 402 | subscription_required |
The tenant’s subscription expired (reviews, signals, device checks only) | no |
| 403 | tenant_not_active |
Tenant still in setup or suspended; can last up to 30 s after setup completes | later |
| 403 | feature_not_in_plan |
The plan does not include reviews, signals or the device connector | no |
| 403 | reporter_suspended |
Reports of this reporter are suspended (Art. 23 DSA) until suspendedUntil; nothing was stored |
no, not before suspendedUntil |
| 403 | appeal_not_allowed |
This person may not complain against this decision | no |
| 404 | not_found |
Unknown ID or path, or the ID belongs to another app | no |
| 405 | method_not_allowed |
Wrong HTTP method for the path | no |
| 409 | idempotency_key_reused |
The key was used for a different body | no, fix key generation |
| 409 | appeal_window_closed |
The six months for a complaint are over | no |
| 409 | appeal_already_open |
This person already has an open complaint against the decision | no |
| 409 | device_connector_not_configured |
The platform is not active for the app, or test without test mode |
no |
| 429 | rate_limited |
Rate limit exceeded, header Retry-After in seconds |
yes, after Retry-After |
| 500 | internal |
Server error | yes |
| 502, 503, 504 | possibly without a problem body | Temporarily unavailable (e.g. during a deployment) | yes |
Reports, complaints and the two subjects operations are never refused because of the tenant’s plan or subscription. Which codes an operation can return is listed on its page and in the OpenAPI specification.
Pagination
No /v1 operation returns a list, so there is no pagination. Batch operations take at most 100 items per request (POST /v1/signals), and webhook events with many items are split (reports.resolved, see Webhook events).
Plans
Reports, complaints and the user operations work with every plan and also after a subscription expired. Review requests, signals and device checks need a plan that includes them: otherwise they answer 403 feature_not_in_plan, and with an expired subscription 402 subscription_required. Do not publish unreviewed content when POST /v1/reviews fails; submit it again later.