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:

HTTP
GET /v1/ping HTTP/1.1
Host: app.limenia.eu
Authorization: Bearer lm_live_...
  • The scheme is Bearer with 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 with lm_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_KEY in 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:

Shell
curl -sS "$LIMENIA_BASE_URL/v1/ping" -H "Authorization: Bearer $LIMENIA_API_KEY"
JSON
{ "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 /v1 stays stable. Changes within /v1 are 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 action or event type) 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: context objects 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 first 0 to 7. Webhook event IDs are evt_ plus a ULID.
  • External IDs (externalUserId, externalContentId, externalReportId and 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_failed with a field error at Idempotency-Key.
  • POST /v1/devices/check takes 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 carries Retry-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 GET operations and repeated requests).
  • A request with up to 100 signals counts once, so batch signals.
  • Over the limit: 429 rate_limited with Retry-After in 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_limited with Retry-After for 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:

JSON
{
  "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 status and code, never on title, detail or message; those are for people and may change. detail can be missing.
  • errors[] lists field errors: field is a JSON pointer into the body (/content/media/0/url), a header name (Idempotency-Key) or a path parameter (externalUserId); code is required, invalid, too_long, too_many, too_large, unknown, not_allowed or too_many_values (a header sent twice); message is an optional hint.
  • reporter_suspended adds suspendedUntil.
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.