Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

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
HeaderValeur
AuthorizationBearer lyr_ing_... (une clé d'ingestion), Bearer lyr_srv_... (une clé serveur), ou une clé à accès complet
Content-Typeapplication/x-ndjson (application/jsonl fonctionne aussi)
Content-Encodinggzip (facultatif, recommandé), ou identity / rien pour du texte brut
X-Lyrelog-AttestationFacultatif. 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 400 pour 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

ChampObligatoireRègles
event_idOuiUn 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.
tsOuiRFC 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.
levelNontrace, debug, info (par défaut), notice, warning, error, critical
categoryNonJusqu'à 64 octets : le domaine de l'app (checkout, sync)
messageOuiJusqu'à 2 048 octets. Un nom d'événement stable (checkout_done), pas une phrase.
user_idNonJusqu'à 128 octets
install_idNonJusqu'à 128 octets
session_idNonJusqu'à 128 octets
attrsNonVoir plus bas
payloadNonN'importe quel JSON jusqu'à 64 KiB une fois sérialisé. Stocké compressé, sans recherche possible dessus.
resourceNonVoir 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é.

StatutSignificationCe 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 4xxLe lot lui-même est invalideLe supprimer : il échouerait de nouveau.
3xxPas une réponse de l'ingestion : l'endpoint est incorrectNe pas la suivre ; corriger l'endpoint.
401, 403Clé inconnue, révoquée ou en lecture seuleArrêter les envois jusqu'au prochain lancement ; garder les données.
408, 425, 429, 5xx, erreur réseauTemporaireGarder 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

StatuterrorCe qu'il faut corriger
415Content-Type must be application/x-ndjsonEnvoyer application/x-ndjson ou application/jsonl
400unsupported Content-Encoding "br" (use gzip)Envoyer gzip, ou aucun Content-Encoding
400body is not valid gzipCompresser tout le corps avec gzip
400empty batchEnvoyer au moins un événement
400too many events in one batch (max 2000)Découper le lot
413body too large, body too large once decompressedGarder 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}
ChampSignification
errorCe qui s'est passé, pour qu'une personne le lise
limit_kindplan (les événements mensuels de Free) ou spending_cap (les événements que couvre le plafond d'une organisation Pro)
planL'offre de l'organisation
limitLes événements que l'offre inclut chaque mois, ou que le plafond couvre
usedLes é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.

RouteCorpsRé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_id est l'id de clé en base64 que renvoie DCAppAttestService ; attestation et assertion sont en base64. L'app passe le SHA-256 des octets UTF-8 du challenge comme clientDataHash.
  • /v1/attest/key est appelée une fois par installation, avec l'attestation d'une nouvelle clé. /v1/attest/token renouvelle le token avec une assertion faite avec cette clé. Une attestation ou une assertion qui ne se vérifie pas reçoit 400.
  • 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 porte X-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.

RouteCorpsRé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/key est 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 le key_id qu'elle renvoie.
  • /v1/attest/android/token renouvelle le token : signature est 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/key peut répondre 503 avec Retry-After : redemandez plus tard.
  • Les tokens fonctionnent comme ceux d'App Attest : 24 heures, dans X-Lyrelog-Attestation, renew quand 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 :

HeaderValeur
Access-Control-Allow-Origin*
Access-Control-Allow-MethodsPOST, OPTIONS
Access-Control-Allow-HeadersAuthorization, Content-Type, Content-Encoding
Access-Control-Expose-HeadersRetry-After
Access-Control-Max-Age86400

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"}}
EOF2

Plusieurs é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.gz

Une 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 :

errorCe qu'il faut corriger
event_id must be a UUID stringEnvoyer 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 stringChaque é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 attrsUn nom d'attribut avec un point ou un _ initial : imbriquez plutôt un objet
attrs.tags: arrays may only hold stringsLes tableaux de attrs ne contiennent que des chaînes
event_id repeated in this batchChaque événement a son propre id

Santé

GET https://ingest.lyrelog.com/healthz

200 {"status":"ok","storage":true,"database":true}, ou 503 avec "status":"degraded" quand le stockage ou la base de données est indisponible.