Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

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
HeaderWert
AuthorizationBearer lyr_ing_... (ein Ingest-Schlüssel), Bearer lyr_srv_... (ein Server-Schlüssel) oder ein Vollzugriffs-Schlüssel
Content-Typeapplication/x-ndjson (application/jsonl geht auch)
Content-Encodinggzip (optional, empfohlen), oder identity / keiner für unkomprimierten Text
X-Lyrelog-AttestationOptional. 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 400 fü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

FeldPflichtRegeln
event_idJaEine 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.
tsJaRFC 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.
levelNeintrace, debug, info (Standard), notice, warning, error, critical
categoryNeinBis zu 64 Byte: der Bereich der App (checkout, sync)
messageJaBis zu 2.048 Byte. Ein stabiler Event-Name (checkout_done), kein Fließtext.
user_idNeinBis zu 128 Byte
install_idNeinBis zu 128 Byte
session_idNeinBis zu 128 Byte
attrsNeinSiehe unten
payloadNeinBeliebiges JSON bis 64 KiB in serialisierter Form. Wird komprimiert gespeichert, nicht durchsuchbar.
resourceNeinSiehe 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.

StatusBedeutungWas 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 4xxDer Batch selbst ist fehlerhaftIhn löschen: Er würde wieder scheitern.
3xxKeine Antwort vom Ingest: Der Endpoint ist falschNicht folgen; den Endpoint korrigieren.
401, 403Unbekannter, widerrufener oder reiner Lese-SchlüsselBis zum nächsten Start nichts mehr senden; die Daten behalten.
408, 425, 429, 5xx, NetzwerkfehlerVorübergehendDieselben 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

StatuserrorWas zu korrigieren ist
415Content-Type must be application/x-ndjsonapplication/x-ndjson oder application/jsonl senden
400unsupported Content-Encoding "br" (use gzip)gzip senden oder kein Content-Encoding
400body is not valid gzipDen ganzen Body mit gzip komprimieren
400empty batchMindestens ein Event senden
400too many events in one batch (max 2000)Den Batch aufteilen
413body too large, body too large once decompressedJeden 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}
FeldBedeutung
errorWas passiert ist, für Menschen lesbar
limit_kindplan (die Monats-Events von Free) oder spending_cap (die Events, die das Limit einer Pro-Organisation abdeckt)
planDer Plan der Organisation
limitDie Events, die der Plan pro Monat enthält oder die das Limit abdeckt
usedDie 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.

RouteBodyAntwort
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_id ist die Base64-Schlüssel-ID, die DCAppAttestService zurückgibt; attestation und assertion sind Base64. Die App übergibt den SHA-256 der UTF-8-Bytes der Challenge als clientDataHash.
  • /v1/attest/key wird einmal pro Installation aufgerufen, mit der Attestierung eines neuen Schlüssels. /v1/attest/token erneuert das Token mit einer Assertion, die mit diesem Schlüssel erstellt wurde. Eine Attestierung oder Assertion, die die Prüfung nicht besteht, bekommt 400.
  • 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ägt X-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.

RouteBodyAntwort
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/key wird 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 die key_id auf, mit der der Server antwortet.
  • /v1/attest/android/token erneuert das Token: signature ist 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/key mit 503 und Retry-After antworten: 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:

HeaderWert
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

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

Mehrere 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.gz

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

errorWas zu korrigieren ist
event_id must be a UUID stringEine 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 stringJedes 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 attrsEin Attributname mit Punkt oder führendem _: verschachtle stattdessen ein Objekt
attrs.tags: arrays may only hold stringsArrays in attrs enthalten nur Strings
event_id repeated in this batchJedes Event bekommt seine eigene ID

Health

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

200 {"status":"ok","storage":true,"database":true}, oder 503 mit "status":"degraded", wenn der Speicher oder die Datenbank ausgefallen ist.