HTTP API
Events ohne SDK senden. Der Ingest-Endpoint, jedes Feld und jedes Limit, und was ein Client mit jeder Antwort tun soll.
Die SDKs nutzen diese API, und alles andere, was HTTP spricht, kann es auch. Wenn diese Seite und ein SDK sich widersprechen, gilt diese Seite.
Der Endpoint
POST https://ingest.lyrelog.com/v1/events:batch| Header | Wert |
|---|---|
Authorization | Bearer lyr_ing_... (ein Ingest-Schlüssel), Bearer lyr_srv_... (ein Server-Schlüssel) oder ein Vollzugriffs-Schlüssel |
Content-Type | application/x-ndjson (application/jsonl geht auch) |
Content-Encoding | gzip (optional, empfohlen), oder identity / keiner für unkomprimierten Text |
X-Lyrelog-Attestation | Optional. Ein Token aus einer Apple- oder Android-App mit Ingest-Schlüssel (siehe Apple App Attest und Android Key Attestation) |
Ein Lese-Schlüssel kann keine Events senden: Er bekommt 403. Nutze auf einem Server einen
Server-Schlüssel: Seine Events sind verifiziert, und der Tagesanteil
einer einzelnen Absenderadresse gilt für ihn nicht. Apps und Webseiten nutzen den Ingest-Schlüssel; die Events einer
Apple-App lassen sich mit App Attest verifizieren, die einer Android-App mit
Key Attestation.
Der Body: NDJSON
Ein JSON-Objekt pro Zeile, eine Zeile pro Event.
- Mindestens ein Event und höchstens 2.000 Zeilen pro Request. Ein leerer Body oder einer mit
mehr Zeilen bekommt
400für den ganzen Batch. - Höchstens 4 MiB über die Leitung und 4 MiB nach dem Dekomprimieren, und 1 MiB für eine Zeile (eine längere Zeile wird einzeln abgelehnt).
- Leerzeilen werden ignoriert, zählen aber bei der Zeilennummerierung mit (damit Fehler auf die richtige Zeile zeigen).
{"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"}}Felder
| Feld | Pflicht | Regeln |
|---|---|---|
event_id | Ja | Eine UUID, einmal pro Event erzeugt. Ein erneutes Senden mit derselben ID und demselben ts wird zusammengeführt. Dieselbe ID zweimal in einem Batch führt zur Ablehnung der zweiten Zeile. |
ts | Ja | RFC 3339 mit Zeitzone. Liegt er bis zu einen Tag in der Zukunft, wird der Wert so gespeichert, wie er gesendet wurde. Liegt er weiter in der Zukunft oder ist er älter als die Aufbewahrungsdauer des Projekts, wird das Event mit der Ankunftszeit gespeichert, und die gesendete Zeit landet im Attribut _lyrelog_ts_clamped. |
level | Nein | trace, debug, info (Standard), notice, warning, error, critical |
category | Nein | Bis zu 64 Byte: der Bereich der App (checkout, sync) |
message | Ja | Bis zu 2.048 Byte. Ein stabiler Event-Name (checkout_done), kein Fließtext. |
user_id | Nein | Bis zu 128 Byte |
install_id | Nein | Bis zu 128 Byte |
session_id | Nein | Bis zu 128 Byte |
attrs | Nein | Siehe unten |
payload | Nein | Beliebiges JSON bis 64 KiB in serialisierter Form. Wird komprimiert gespeichert, nicht durchsuchbar. |
resource | Nein | Siehe unten |
Unbekannte Felder werden abgelehnt, damit ein Tippfehler auffällt, statt still zu verschwinden.
attrs
Kleine Felder zum Filtern und für Diagramme.
- Werte: Strings (bis 1.024 Byte), Zahlen, Booleans, null, Arrays aus Strings (bis 64 Elemente) und verschachtelte Objekte (bis 4 Ebenen).
- Insgesamt höchstens 200 Blattwerte.
- Namen: bis 128 Byte, keine Punkte (verschachtle stattdessen ein Objekt), kein führendes
_.
resource
Nur diese Schlüssel, jeder bis 64 Byte:
app_id, app_version, app_build, os_name, os_version, device_model, locale, sdk,
environment, platform.
environment und platform bestehen aus Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen,
und beginnen mit einem Buchstaben oder einer Ziffer. Ohne environment wird das Event als
production gespeichert. Ohne platform leitet der Server eine aus sdk und os_name ab.
Vom Server hinzugefügt
country: der ISO-Code der Adresse, von der der Batch kam, auf jedem Event des Batches. Ein Client
kann ihn nicht setzen, und die Adresse wird nicht gespeichert. Siehe Länder.
verified_by: server, wenn der Batch mit einem Server-Schlüssel kam, app_attest oder
key_attestation, wenn er mit einem Ingest-Schlüssel und einem gültigen
App Attest- oder Key Attestation-Token kam,
sonst leer. Ein Client kann es nicht setzen: Eine Zeile mit verified_by wird mit
unknown fields: verified_by abgelehnt. Siehe Verifizierte Events.
Antworten
Jede Antwort ist JSON. Ein Fehler hat ein Feld error, das sagt, was schiefgelaufen ist.
| Status | Bedeutung | Was der Client tut |
|---|---|---|
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]} | Gespeichert. Abgelehnte Zeilen sind ungültig. | Den Batch löschen. Die abgelehnten Zeilen nie erneut senden. |
400, 413, 415, jeder andere 4xx | Der Batch selbst ist fehlerhaft | Ihn löschen: Er würde wieder scheitern. |
| 3xx | Keine Antwort vom Ingest: Der Endpoint ist falsch | Nicht folgen; den Endpoint korrigieren. |
401, 403 | Unbekannter, widerrufener oder reiner Lese-Schlüssel | Bis zum nächsten Start nichts mehr senden; die Daten behalten. |
408, 425, 429, 5xx, Netzwerkfehler | Vorübergehend | Dieselben Bytes behalten, mit Backoff erneut versuchen, Retry-After beachten. |
Ein Batch wird in dieser Reihenfolge geprüft: der Schlüssel, dann Content-Type und die angegebene
Größe, dann das Monatskontingent, der Tagesanteil einer Adresse und das Ratenlimit (alles, bevor der
Body gelesen wird), dann der Body und seine Zeilen. Ein Batch, der an einer Prüfung scheitert,
bekommt diese Antwort und speichert nichts. Abgelehnte Zeilen zählen zum Ratenlimit. Gleichzeitig
gesendete Batches können das Monatskontingent leicht überschreiten, bevor es greift.
Das Widerrufen eines Schlüssels wirkt sofort; rechne mit bis zu einer Minute.
400, 413, 415: der Batch selbst
| Status | error | Was zu korrigieren ist |
|---|---|---|
415 | Content-Type must be application/x-ndjson | application/x-ndjson oder application/jsonl senden |
400 | unsupported Content-Encoding "br" (use gzip) | gzip senden oder kein Content-Encoding |
400 | body is not valid gzip | Den ganzen Body mit gzip komprimieren |
400 | empty batch | Mindestens ein Event senden |
400 | too many events in one batch (max 2000) | Den Batch aufteilen |
413 | body too large, body too large once decompressed | Jeden Batch unter 4 MiB halten, vor und nach gzip |
429: das Monatskontingent
Eine Free-Organisation hat 1.000.000 Events im Monat inklusive, für alle ihre Projekte zusammen. Darüber
hinaus bekommt jeder Batch 429, bis der nächste Monat beginnt (am 1., UTC) oder bis die
Organisation in einen anderen Plan wechselt. Eine Pro-Organisation mit einem
Ausgabenlimit bekommt dasselbe bei den Events, die ihr
Limit abdeckt, mit 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}| Feld | Bedeutung |
|---|---|
error | Was passiert ist, für Menschen lesbar |
limit_kind | plan (die Monats-Events von Free) oder spending_cap (die Events, die das Limit einer Pro-Organisation abdeckt) |
plan | Der Plan der Organisation |
limit | Die Events, die der Plan pro Monat enthält oder die das Limit abdeckt |
used | Die bisher in diesem Monat gezählten Events |
Retry-After gibt die Sekunden bis zum nächsten Monat an, aber nie mehr als eine Stunde, damit
ein Upgrade schnell greift. Behandle es wie jedes andere 429: Behalte den Batch und sende ihn
später erneut. Die SDKs erledigen das für dich, im Rahmen der Limits ihrer Warteschlange (siehe
was wo wartet), und loggen beim ersten Mal eine Warnung.
Am Feld plan unterscheidest du dieses 429 von den anderen beiden: Der Tagesanteil
einer Adresse hat stattdessen source_limit, und der Body des Ratenlimits hat nur error.
429: der Tagesanteil einer Adresse
Mit einem öffentlichen Schlüssel (einem Ingest- oder Vollzugriffs-Schlüssel) darf eine
Adresse an einem UTC-Tag höchstens ein Fünfzigstel der monatlichen Events des Plans senden, für
alle Projekte der Organisation zusammen: Free 20.000, Pro 200.000, Business 4.000.000, Unlimited
ohne Limit. IPv6-Adressen zählen pro /64. Verifizierte Batches (ein Server-Schlüssel oder ein
gültiges App-Attest- oder Key-Attestation-Token) sind davon ausgenommen. Darüber hinaus bekommen
Batches von dieser Adresse 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 ist die Zahl der Events, die eine Adresse pro Tag senden darf. Retry-After gibt die
Sekunden bis zum nächsten UTC-Tag an, höchstens eine Stunde. Andere Adressen senden weiter.
Behandle es wie jedes andere 429; bekommt es ein Server, gib diesem Server einen
Server-Schlüssel. Warum es das gibt:
Verifizierte Events.
425: nur verifizierte Events
Ein Projekt kann von einer Plattform nur verifizierte Events annehmen (ein Inhaber schaltet das
in den Einstellungen des Projekts ein; standardmäßig aus). Ein nicht verifizierter Batch mit einem
Event dieser Plattform bekommt 425 Too Early, Retry-After: 30 und
{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}
(oder android).
Vom Batch wird nichts gespeichert. Behalte ihn und sende ihn erneut, mit einem gültigen
X-Lyrelog-Attestation-Token, sobald du eines hast: Die SDKs tun das von selbst.
Verifizierte Events.
429: das Ratenlimit
Jedes Projekt nimmt standardmäßig höchstens 60.000 Events pro Minute an. Ein Batch darüber bekommt
429 mit {"error":"rate limit for this project"} und ein Retry-After in Sekunden.
429: unbekannte Schlüssel
Eine Adresse, die mehr als 30 unbekannte Schlüssel in einer Minute sendet, bekommt 429 mit
Retry-After: 60. Ein Token, das nicht wie ein Lyrelog-Schlüssel aufgebaut ist, bekommt sofort
401.
503
Der Server erreicht gerade seine Datenbank oder seinen Speicher nicht, oder er ist mit anderen
Batches beschäftigt. Er antwortet mit Retry-After: 5. Sende dieselben Bytes erneut.
Idempotenz
Die Zustellung erfolgt mindestens einmal. Wenn ein erneuter Versuch ein Duplikat sein könnte, sende
genau dieselben Zeilen erneut: Events mit derselben event_id und demselben ts werden zu
einem zusammengeführt. Erzeuge für einen erneuten Versuch nie neue IDs.
Apple App Attest
Eine Apple-App auf einem echten iPhone, iPad oder einer Apple Watch kann beweisen, dass sie die
echte App des Projekts ist, und ihre Events werden dann mit verified_by auf app_attest
gespeichert. Das Swift-SDK ist der Client (auch unter React Native
und Flutter) und erledigt all das selbst; dieser Abschnitt dient als Referenz. Was es beweist und
wie du es einrichtest: Verifizierte Events.
Die drei Routen nehmen einen JSON-Body und den Ingest-Schlüssel des Projekts als Bearer und
zählen jeweils wie ein Event zur Rate des Projekts. Sie antworten mit 404, bis ein Inhaber in
den Einstellungen des Projekts eine App ID hinzugefügt hat, und mit 403 auf jeden anderen
Schlüssel (die Events eines Server-Schlüssels sind bereits verifiziert). Sie haben kein CORS: Sie
sind für Apps gedacht, nicht für Webseiten.
| Route | Body | Antwort |
|---|---|---|
POST /v1/attest/challenge | {} | {"challenge":"..."}: einmal verwendbar, 5 Minuten lang, nur für dieses Projekt |
POST /v1/attest/key | {"key_id","attestation","challenge"} | {"token","expires_at"} |
POST /v1/attest/token | {"key_id","assertion","challenge"} | {"token","expires_at"}, oder 404 für einen Schlüssel, den das Projekt nicht kennt: erneut attestieren |
key_idist die Base64-Schlüssel-ID, dieDCAppAttestServicezurückgibt;attestationundassertionsind Base64. Die App übergibt den SHA-256 der UTF-8-Bytes der Challenge alsclientDataHash./v1/attest/keywird einmal pro Installation aufgerufen, mit der Attestierung eines neuen Schlüssels./v1/attest/tokenerneuert das Token mit einer Assertion, die mit diesem Schlüssel erstellt wurde. Eine Attestierung oder Assertion, die die Prüfung nicht besteht, bekommt400.- Ein Token ist 24 Stunden gültig. Ein Batch trägt es im Header
X-Lyrelog-Attestation. Ein gültiges macht den Batch verifiziert und nimmt ihn vom Tagesanteil einer Adresse aus. Ohne Token ändert sich nichts. Eines, das nichts beweist (abgelaufen, von einem anderen Projekt oder gar kein Token), lässt den Batch unverifiziert, und die Antwort trägtX-Lyrelog-Attestation: renew, damit die App ein neues holt. - Ein Batch wird nie wegen seines Tokens abgewiesen.
Android Key Attestation
Eine Android-App auf einem echten Gerät kann beweisen, dass sie die echte App des Projekts ist,
signiert mit deinem Zertifikat, auf einem Gerät, das nicht manipuliert wurde. Ihre Events werden
dann mit verified_by auf key_attestation gespeichert. Das
Android-SDK ist der Client (auch unter React Native und Flutter)
und erledigt all das selbst; dieser Abschnitt dient als Referenz. Was es beweist und wie du es
einrichtest: Verifizierte Events.
Es gelten dieselben Regeln wie bei App Attest: ein JSON-Body, der Ingest-Schlüssel des
Projekts als Bearer (403 für jeden anderen Schlüssel), jeder Aufruf zählt als ein Event
zur Rate des Projekts, kein CORS, und 404, bis ein Inhaber in den Einstellungen des Projekts eine Android-App (ihr Package
und ihr Signaturzertifikat) hinzugefügt hat. Die Challenge kommt von derselben Route,
POST /v1/attest/challenge.
| Route | Body | Antwort |
|---|---|---|
POST /v1/attest/android/key | {"challenge","chain":[...]} | {"token","expires_at","key_id"} |
POST /v1/attest/android/token | {"key_id","challenge","signature"} | {"token","expires_at"}, oder 404 für einen Schlüssel, den das Projekt nicht kennt: erneut attestieren |
/v1/attest/android/keywird einmal pro Installation aufgerufen. Die App erzeugt im Android Keystore einen EC-P-256-Schlüssel mit den UTF-8-Bytes der Challenge als Attestation-Challenge und sendet die Zertifikatskette des Schlüssels, Leaf zuerst, jedes Zertifikat als Standard-Base64-DER. Bewahre diekey_idauf, mit der der Server antwortet./v1/attest/android/tokenerneuert das Token:signatureist die Base64-ECDSA-Signatur (SHA256withECDSA, DER) über die UTF-8-Bytes einer neuen Challenge, erstellt mit diesem Schlüssel.- Eine Kette oder Signatur, die die Prüfung nicht besteht, bekommt
400. Direkt nach dem Start des Servers, bevor er Googles Liste widerrufener Zertifikate hat, kann/v1/attest/android/keymit503undRetry-Afterantworten: Frag später noch einmal. - Tokens funktionieren wie bei App Attest: 24 Stunden, in
X-Lyrelog-Attestation,renew, wenn eines nichts beweist, und ein Batch wird nie wegen seines Tokens abgewiesen.
CORS
Der Endpoint antwortet Browsern von jeder Origin, sodass eine Webseite Events direkt senden kann:
| Header | Wert |
|---|---|
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 |
Die Wildcard ist sicher, weil keine Cookies im Spiel sind und ein Ingest-Schlüssel nur Events anhängen kann. Die eigene API des Dashboards hat kein CORS.
Beispiele
In diesen Beispielen enthält die Shell-Variable $LYRELOG_KEY einen der Schlüssel des Projekts
(setze sie selbst: export LYRELOG_KEY=lyr_srv_...). Nutze auf einem Server oder in einem
Cronjob, wie hier, einen Server-Schlüssel, lyr_srv_...; ein Ingest-Schlüssel, lyr_ing_...,
funktioniert auch, aber seine Events sind nicht verifiziert.
Ein Event
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"}}
EOF2Mehrere Events, mit 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.gzEine abgelehnte Zeile
Die zweite Zeile hat einen Tippfehler, 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 @-Die erste Zeile wird gespeichert, die zweite nicht:
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}Häufige Fehler in Zeilen:
error | Was zu korrigieren ist |
|---|---|
event_id must be a UUID string | Eine UUID senden, etwa 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f |
ts must carry a time zone (use Z for UTC) | 2026-11-18T10:00:00Z, nicht 2026-11-18T10:00:00 |
message must be a non-empty string | Jedes Event braucht eine message |
unknown fields: ..., unknown resource fields: ... | Ein Tippfehler oder ein Feld, das Lyrelog nicht annimmt (auch verified_by und country, die nur der Server setzt) |
bad attribute name "..." in attrs | Ein Attributname mit Punkt oder führendem _: verschachtle stattdessen ein Objekt |
attrs.tags: arrays may only hold strings | Arrays in attrs enthalten nur Strings |
event_id repeated in this batch | Jedes Event bekommt seine eigene ID |
Health
GET https://ingest.lyrelog.com/healthz200 {"status":"ok","storage":true,"database":true}, oder 503 mit "status":"degraded", wenn
der Speicher oder die Datenbank ausgefallen ist.