HTTP API
Envoyer des événements sans SDK. L'endpoint d'ingestion, chaque champ et chaque limite, et ce qu'un client doit faire de chaque réponse.
Les SDK utilisent cette API, et tout ce qui parle HTTP peut le faire aussi. Quand cette page et un SDK divergent, c'est cette page qui fait foi.
L'endpoint
POST https://ingest.lyrelog.com/v1/events:batch| Header | Valeur |
|---|---|
Authorization | Bearer lyr_ing_... (une clé d'ingestion), Bearer lyr_srv_... (une clé serveur), ou une clé à accès complet |
Content-Type | application/x-ndjson (application/jsonl fonctionne aussi) |
Content-Encoding | gzip (facultatif, recommandé), ou identity / rien pour du texte brut |
X-Lyrelog-Attestation | Facultatif. Un token d'une app Apple ou Android avec une clé d'ingestion (voir Apple App Attest et Android Key Attestation) |
Une clé de lecture ne peut pas envoyer d'événements : elle reçoit 403. Depuis un serveur, utilisez
une clé serveur : ses événements sont vérifiés et le quota journalier d'une adresse
ne s'y applique pas. Les apps et les pages web utilisent la clé d'ingestion ; les événements d'une app
Apple peuvent être vérifiés avec App Attest, ceux d'une app Android avec
Key Attestation.
Le corps : NDJSON
Un objet JSON par ligne, une ligne par événement.
- Au moins un événement et au plus 2 000 lignes par requête. Un corps vide, ou qui contient
davantage de lignes, reçoit
400pour tout le lot. - Au plus 4 MiB sur le réseau et 4 MiB une fois décompressé, et 1 MiB pour une ligne (une ligne plus longue est rejetée à elle seule).
- Les lignes vides sont ignorées, mais comptent quand même dans la numérotation (pour que les erreurs désignent la bonne ligne).
{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":"2026-11-18T10:00:00.123Z","level":"info","category":"checkout","message":"checkout_done","user_id":"user-1","install_id":"8c1d...","session_id":"2f9a...","attrs":{"items":3,"latency_ms":412,"payment":{"method":"card"},"tags":["a","b"]},"payload":{"response":"..."},"resource":{"app_id":"com.example.app","app_version":"2.0","app_build":"202611181200","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,1","locale":"es_ES","sdk":"lyrelog-swift/0.1.0","environment":"production","platform":"ios"}}Champs
| Champ | Obligatoire | Règles |
|---|---|---|
event_id | Oui | Un UUID créé une seule fois par événement. Un renvoi avec le même id et le même ts est fusionné. Le même id deux fois dans un lot fait rejeter la seconde ligne. |
ts | Oui | RFC 3339 avec un fuseau. Jusqu'à un jour d'avance sur le serveur, il est conservé tel qu'envoyé. Au-delà, ou s'il est plus ancien que la durée de conservation du projet, l'événement est enregistré à l'heure d'arrivée et l'heure envoyée va dans l'attribut _lyrelog_ts_clamped. |
level | Non | trace, debug, info (par défaut), notice, warning, error, critical |
category | Non | Jusqu'à 64 octets : le domaine de l'app (checkout, sync) |
message | Oui | Jusqu'à 2 048 octets. Un nom d'événement stable (checkout_done), pas une phrase. |
user_id | Non | Jusqu'à 128 octets |
install_id | Non | Jusqu'à 128 octets |
session_id | Non | Jusqu'à 128 octets |
attrs | Non | Voir plus bas |
payload | Non | N'importe quel JSON jusqu'à 64 KiB une fois sérialisé. Stocké compressé, sans recherche possible dessus. |
resource | Non | Voir plus bas |
Les champs inconnus sont rejetés, pour qu'une faute de frappe se voie au lieu de disparaître.
attrs
De petits champs pour filtrer et faire des graphiques.
- Valeurs : chaînes (jusqu'à 1 024 octets), nombres, booléens, null, tableaux de chaînes (jusqu'à 64 éléments) et objets imbriqués (jusqu'à 4 niveaux).
- Au plus 200 feuilles au total.
- Noms : jusqu'à 128 octets, sans point (imbriquez plutôt un objet), sans
_initial.
resource
Uniquement ces clés, chacune jusqu'à 64 octets :
app_id, app_version, app_build, os_name, os_version, device_model, locale, sdk,
environment, platform.
environment et platform ne contiennent que des lettres minuscules, des chiffres, - et _,
jusqu'à 32 caractères, et commencent par une lettre ou un chiffre. Sans environment, l'événement
est enregistré en production. Sans platform, le serveur en déduit une à partir de sdk et
os_name.
Ajoutés par le serveur
country : le code ISO de l'adresse d'où vient le lot, sur chaque événement du lot. Un client ne
peut pas le définir, et l'adresse n'est pas conservée. Voir Pays.
verified_by : server quand le lot est arrivé avec une clé serveur, app_attest ou
key_attestation quand il est arrivé avec une clé d'ingestion et un token
App Attest ou Key Attestation valide, vide sinon.
Un client ne peut pas le définir : une ligne qui contient verified_by est rejetée avec
unknown fields: verified_by. Voir Événements vérifiés.
Réponses
Chaque réponse est en JSON. Une erreur a un champ error qui dit ce qui n'a pas marché.
| Statut | Signification | Ce que fait le client |
|---|---|---|
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]} | Enregistré. Les lignes rejetées sont invalides. | Supprimer le lot. Ne jamais renvoyer les lignes rejetées. |
400, 413, 415, tout autre 4xx | Le lot lui-même est invalide | Le supprimer : il échouerait de nouveau. |
| 3xx | Pas une réponse de l'ingestion : l'endpoint est incorrect | Ne pas la suivre ; corriger l'endpoint. |
401, 403 | Clé inconnue, révoquée ou en lecture seule | Arrêter les envois jusqu'au prochain lancement ; garder les données. |
408, 425, 429, 5xx, erreur réseau | Temporaire | Garder les mêmes octets, réessayer avec backoff, respecter Retry-After. |
Un lot est contrôlé dans cet ordre : la clé, puis Content-Type et la taille déclarée, puis le
quota mensuel, le quota journalier d'une adresse et la limite de débit (tout cela avant de lire le
corps), puis le corps et ses lignes. Un lot qui ne passe pas un contrôle reçoit la réponse
correspondante et rien n'est enregistré. Les lignes rejetées comptent dans la limite de débit. Des
lots envoyés au même moment peuvent dépasser un peu le quota mensuel avant qu'il ne s'applique.
La révocation d'une clé prend effet immédiatement ; comptez jusqu'à une minute.
400, 413, 415 : le lot lui-même
| Statut | error | Ce qu'il faut corriger |
|---|---|---|
415 | Content-Type must be application/x-ndjson | Envoyer application/x-ndjson ou application/jsonl |
400 | unsupported Content-Encoding "br" (use gzip) | Envoyer gzip, ou aucun Content-Encoding |
400 | body is not valid gzip | Compresser tout le corps avec gzip |
400 | empty batch | Envoyer au moins un événement |
400 | too many events in one batch (max 2000) | Découper le lot |
413 | body too large, body too large once decompressed | Garder chaque lot sous 4 MiB, avant et après gzip |
429 : le quota mensuel
Une organisation Free inclut 1 000 000 événements par mois, pour tous ses projets réunis. Au-delà,
chaque lot reçoit 429 jusqu'au début du mois suivant (le 1er, en UTC), ou jusqu'à ce que
l'organisation change d'offre. Une organisation Pro avec un
plafond de dépenses reçoit la même réponse une fois atteints
les événements que son plafond couvre, avec limit_kind spending_cap :
{"error":"this organization's free plan includes 1000000 events a month and they're used: upgrade it, or events resume on 1 December","limit_kind":"plan","plan":"free","limit":1000000,"used":1000412}| Champ | Signification |
|---|---|
error | Ce qui s'est passé, pour qu'une personne le lise |
limit_kind | plan (les événements mensuels de Free) ou spending_cap (les événements que couvre le plafond d'une organisation Pro) |
plan | L'offre de l'organisation |
limit | Les événements que l'offre inclut chaque mois, ou que le plafond couvre |
used | Les événements comptés jusqu'ici ce mois-ci |
Retry-After donne les secondes jusqu'au mois suivant, mais jamais plus d'une heure, pour qu'un
passage à une offre supérieure prenne vite effet. Traitez-le comme n'importe quel autre 429 :
gardez le lot et renvoyez-le plus tard. Les SDK le font pour vous, dans les limites de leur file
(voir ce qui attend où), et journalisent un avertissement la
première fois. C'est le champ plan qui distingue ce 429 des deux autres : le quota journalier
d'une adresse a source_limit à la place, et le corps de la limite de débit n'a que error.
429 : le quota journalier d'une adresse
Avec une clé publique (une clé d'ingestion ou à accès complet), une adresse peut envoyer au plus un
cinquantième des événements mensuels de l'offre par jour UTC, pour tous les projets de
l'organisation réunis : Free 20 000, Pro 200 000, Business 4 000 000, Unlimited sans limite. Les
adresses IPv6 comptent par /64. Les lots vérifiés (une clé serveur, ou un token App Attest ou Key
Attestation valide) ne sont pas limités ainsi. Au-delà, les lots de cette adresse reçoivent 429 :
{"error":"this address sent 20000 events today with a public key of this organization, its share of the day: a server should use a server key, which has no such limit; events from here resume tomorrow (UTC)","source_limit":20000}source_limit est le nombre d'événements qu'une adresse peut envoyer par jour. Retry-After donne
les secondes jusqu'au jour UTC suivant, au plus une heure. Les autres adresses continuent d'envoyer.
Traitez-le comme n'importe quel autre 429 ; si c'est un serveur qui le reçoit, donnez-lui une clé
serveur. Pourquoi ce quota existe :
Événements vérifiés.
425 : événements vérifiés uniquement
Un projet peut n'accepter que des événements vérifiés pour une plateforme (un propriétaire l'active
dans les réglages du projet ; désactivé par défaut). Un lot non vérifié contenant un événement de
cette plateforme reçoit 425 Too Early, Retry-After: 30 et
{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}
(ou android).
Rien de ce lot n'est enregistré. Gardez-le et renvoyez-le, avec un token X-Lyrelog-Attestation
valide dès que vous en avez un : les SDK le font d'eux-mêmes.
Événements vérifiés.
429 : la limite de débit
Chaque projet accepte par défaut au plus 60 000 événements par minute. Un lot qui la dépasse reçoit
429 avec {"error":"rate limit for this project"} et un Retry-After en secondes.
429 : clés inconnues
Une adresse qui envoie plus de 30 clés inconnues en une minute reçoit 429 avec Retry-After: 60.
Un token qui n'a pas la forme d'une clé Lyrelog reçoit 401 immédiatement.
503
Le serveur ne peut pas joindre sa base de données ou son stockage pour le moment, ou il est occupé
par d'autres lots. Il répond avec Retry-After: 5. Renvoyez les mêmes octets.
Idempotence
La livraison est « au moins une fois ». Quand une nouvelle tentative risque d'être un doublon,
renvoyez exactement les mêmes lignes : les événements de même event_id et même ts sont
fusionnés en un seul. Ne créez jamais de nouveaux ids pour une nouvelle tentative.
Apple App Attest
Une app Apple sur un vrai iPhone, iPad ou Apple Watch peut prouver qu'elle est l'app authentique du
projet, et ses événements sont alors enregistrés avec verified_by à app_attest. Le
SDK Swift est le client (aussi sous React Native et Flutter) et fait
tout cela de lui-même ; cette section sert de référence. Ce que cela prouve, et comment le mettre en
place : Événements vérifiés.
Les trois routes prennent un corps JSON et la clé d'ingestion du projet comme bearer, et
comptent chacune comme un événement dans le débit du projet. Elles répondent 404 tant qu'un
propriétaire n'a pas ajouté d'App ID dans les réglages du projet, et 403 à toute autre clé (les
événements d'une clé serveur sont déjà vérifiés). Elles n'ont pas de CORS : elles sont faites pour
les apps, pas pour les pages web.
| Route | Corps | Réponse |
|---|---|---|
POST /v1/attest/challenge | {} | {"challenge":"..."} : à usage unique, valable 5 minutes, pour ce projet seulement |
POST /v1/attest/key | {"key_id","attestation","challenge"} | {"token","expires_at"} |
POST /v1/attest/token | {"key_id","assertion","challenge"} | {"token","expires_at"}, ou 404 pour une clé que le projet n'a pas : attestez-la de nouveau |
key_idest l'id de clé en base64 que renvoieDCAppAttestService;attestationetassertionsont en base64. L'app passe le SHA-256 des octets UTF-8 du challenge commeclientDataHash./v1/attest/keyest appelée une fois par installation, avec l'attestation d'une nouvelle clé./v1/attest/tokenrenouvelle le token avec une assertion faite avec cette clé. Une attestation ou une assertion qui ne se vérifie pas reçoit400.- Un token est valable 24 heures. Un lot l'envoie dans le header
X-Lyrelog-Attestation. Un token valide rend le lot vérifié et l'exempte du quota journalier d'une adresse. Sans token, rien ne change. Un token qui ne prouve rien (expiré, d'un autre projet, ou qui n'est pas un token) laisse le lot non vérifié, et la réponse porteX-Lyrelog-Attestation: renew, pour que l'app en obtienne un nouveau. - Un lot n'est jamais refusé à cause de son token.
Android Key Attestation
Une app Android sur un vrai appareil peut prouver qu'elle est l'app authentique du projet, signée
avec votre certificat, sur un appareil non altéré. Ses événements sont alors
enregistrés avec verified_by à key_attestation. Le SDK Android
est le client (aussi sous React Native et Flutter) et fait tout cela de lui-même ; cette section sert
de référence. Ce que cela prouve, et comment le mettre en place :
Événements vérifiés.
Les mêmes règles qu'App Attest : un corps JSON, la clé d'ingestion du projet comme bearer (403
pour toute autre clé), chaque appel compte pour un événement dans le débit du projet, pas de CORS, et 404 tant qu'un
propriétaire n'a pas ajouté d'app Android (son package et son certificat de signature) dans les
réglages du projet. Le challenge vient de la même route, POST /v1/attest/challenge.
| Route | Corps | Réponse |
|---|---|---|
POST /v1/attest/android/key | {"challenge","chain":[...]} | {"token","expires_at","key_id"} |
POST /v1/attest/android/token | {"key_id","challenge","signature"} | {"token","expires_at"}, ou 404 pour une clé que le projet n'a pas : attestez-la de nouveau |
/v1/attest/android/keyest appelée une fois par installation. L'app crée une clé EC P-256 dans l'Android Keystore avec les octets UTF-8 du challenge comme challenge d'attestation, et envoie la chaîne de certificats de la clé, feuille en premier, chaque certificat en DER encodé en base64 standard. Gardez lekey_idqu'elle renvoie./v1/attest/android/tokenrenouvelle le token :signatureest la signature ECDSA en base64 (SHA256withECDSA, DER) des octets UTF-8 d'un nouveau challenge, faite avec cette clé.- Une chaîne ou une signature qui ne se vérifie pas reçoit
400. Juste après le démarrage du serveur, avant qu'il ait la liste des certificats révoqués de Google,/v1/attest/android/keypeut répondre503avecRetry-After: redemandez plus tard. - Les tokens fonctionnent comme ceux d'App Attest : 24 heures, dans
X-Lyrelog-Attestation,renewquand l'un d'eux ne prouve rien, et un lot n'est jamais refusé à cause de son token.
CORS
L'endpoint répond aux navigateurs de toute origine, si bien qu'une page web peut envoyer des événements directement :
| Header | Valeur |
|---|---|
Access-Control-Allow-Origin | * |
Access-Control-Allow-Methods | POST, OPTIONS |
Access-Control-Allow-Headers | Authorization, Content-Type, Content-Encoding |
Access-Control-Expose-Headers | Retry-After |
Access-Control-Max-Age | 86400 |
Le joker est sans risque car aucun cookie n'entre en jeu et une clé d'ingestion ne peut qu'ajouter des événements. L'API du tableau de bord, elle, n'a pas de CORS.
Exemples
Dans ces exemples, la variable shell $LYRELOG_KEY contient l'une des clés du projet (définissez-la
vous-même : export LYRELOG_KEY=lyr_srv_...). Depuis un serveur ou une tâche cron, comme ici,
utilisez une clé serveur, lyr_srv_... ; une clé d'ingestion, lyr_ing_..., fonctionne aussi, mais
ses événements ne sont pas vérifiés.
Un événement
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @- <<EOF2
{"event_id":"$(uuidgen | tr A-Z a-z)","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","level":"warning","category":"backup","message":"backup_slow","attrs":{"seconds":412},"resource":{"environment":"production","platform":"cron"}}
EOF2Plusieurs événements, compressés en gzip
cat > batch.ndjson <<EOF2
{"event_id":"$(uuidgen | tr A-Z a-z)","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","message":"deploy_started","attrs":{"version":"2.0.1"}}
{"event_id":"$(uuidgen | tr A-Z a-z)","ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","message":"deploy_finished","attrs":{"version":"2.0.1","seconds":48}}
EOF2
gzip -c batch.ndjson > batch.ndjson.gz
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
-H "Content-Encoding: gzip" \
--data-binary @batch.ndjson.gzUne ligne rejetée
La seconde ligne contient une faute de frappe, mesage :
printf '%s\n' \
"{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"message\":\"ok\"}" \
"{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"mesage\":\"typo\"}" |
curl -s -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @-La première ligne est enregistrée, la seconde non :
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}Erreurs de ligne courantes :
error | Ce qu'il faut corriger |
|---|---|
event_id must be a UUID string | Envoyer un UUID tel que 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f |
ts must carry a time zone (use Z for UTC) | 2026-11-18T10:00:00Z, pas 2026-11-18T10:00:00 |
message must be a non-empty string | Chaque événement a besoin d'un message |
unknown fields: ..., unknown resource fields: ... | Une faute de frappe, ou un champ que Lyrelog n'accepte pas (y compris verified_by et country, que seul le serveur définit) |
bad attribute name "..." in attrs | Un nom d'attribut avec un point ou un _ initial : imbriquez plutôt un objet |
attrs.tags: arrays may only hold strings | Les tableaux de attrs ne contiennent que des chaînes |
event_id repeated in this batch | Chaque événement a son propre id |
Santé
GET https://ingest.lyrelog.com/healthz200 {"status":"ok","storage":true,"database":true}, ou 503 avec "status":"degraded" quand le
stockage ou la base de données est indisponible.