Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

HTTP API

Send events without an SDK. The ingest endpoint, every field and limit, and what a client should do with each answer.

The SDKs use this API, and so can anything that speaks HTTP. When this page and an SDK disagree, this page wins.

The endpoint

POST https://ingest.lyrelog.com/v1/events:batch
HeaderValue
AuthorizationBearer lyr_ing_... (an ingest key), Bearer lyr_srv_... (a server key), or a full-access key
Content-Typeapplication/x-ndjson (application/jsonl works too)
Content-Encodinggzip (optional, recommended), or identity / none for plain text
X-Lyrelog-AttestationOptional. A token from an Apple or Android app with an ingest key (see Apple App Attest and Android Key Attestation)

A read key can't send events: it gets 403. From a server, use a server key: its events are verified and one address has no daily share. Apps and web pages use the ingest key; an Apple app's events can be verified with App Attest, an Android app's with Key Attestation.

The body: NDJSON

One JSON object per line, one line per event.

  • At least one event and at most 2,000 lines per request. An empty body, or one with more lines, gets 400 for the whole batch.
  • At most 4 MiB on the wire and 4 MiB once decompressed, and 1 MiB for one line (a longer line is rejected on its own).
  • Blank lines are ignored but still count in the line numbering (so errors point at the right line).
{"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"}}

Fields

FieldRequiredRules
event_idYesA UUID made once per event. A resend with the same id and ts is collapsed. The same id twice in one batch rejects the second line.
tsYesRFC 3339 with a zone. Up to a day ahead of the server it is kept as sent. Further ahead, or older than the project's retention, the event is stored at the arrival time and the time it was sent goes in the attribute _lyrelog_ts_clamped.
levelNotrace, debug, info (default), notice, warning, error, critical
categoryNoUp to 64 bytes: the area of the app (checkout, sync)
messageYesUp to 2,048 bytes. A stable event name (checkout_done), not prose.
user_idNoUp to 128 bytes
install_idNoUp to 128 bytes
session_idNoUp to 128 bytes
attrsNoSee below
payloadNoAny JSON up to 64 KiB once serialized. Stored compressed, not searchable.
resourceNoSee below

Unknown fields are rejected, so a typo surfaces instead of disappearing.

attrs

Small fields to filter and chart by.

  • Values: strings (up to 1,024 bytes), numbers, booleans, null, arrays of strings (up to 64 items) and nested objects (up to 4 levels).
  • At most 200 leaves in total.
  • Names: up to 128 bytes, no dots (nest an object instead), no leading _.

resource

Only these keys, each up to 64 bytes:

app_id, app_version, app_build, os_name, os_version, device_model, locale, sdk, environment, platform.

environment and platform are lowercase letters, digits, - and _, up to 32 characters, starting with a letter or digit. Without an environment, the event is stored as production. Without a platform, the server derives one from sdk and os_name.

Added by the server

country: the ISO code of the address the batch came from, on every event of the batch. A client can't set it, and the address isn't stored. See Countries.

verified_by: server when the batch came with a server key, app_attest or key_attestation when it came with an ingest key and a valid App Attest or Key Attestation token, empty otherwise. A client can't set it: a line that includes verified_by is rejected with unknown fields: verified_by. See Verified events.

Responses

Every answer is JSON. An error has an error field that says what went wrong.

StatusMeaningWhat the client does
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]}Stored. Rejected lines are invalid.Delete the batch. Never resend the rejected lines.
400, 413, 415, any other 4xxThe batch itself is wrongDelete it: it would fail again.
3xxNot an answer from the ingest: the endpoint is wrongDon't follow it; fix the endpoint.
401, 403Unknown, revoked or read-only keyStop sending until the next launch; keep the data.
408, 425, 429, 5xx, network errorTemporaryKeep the same bytes, retry with backoff, honor Retry-After.

A batch is checked in this order: the key, then Content-Type and the declared size, then the monthly quota, the daily share of one address and the rate limit (all before the body is read), then the body and its lines. A batch that fails one check gets that answer and stores nothing. Rejected lines count against the rate limit. Batches sent at the same moment can go a little past the monthly quota before it applies.

Revoking a key takes effect at once; allow up to a minute.

400, 413, 415: the batch itself

StatuserrorWhat to fix
415Content-Type must be application/x-ndjsonSend application/x-ndjson or application/jsonl
400unsupported Content-Encoding "br" (use gzip)Send gzip, or no Content-Encoding
400body is not valid gzipCompress the whole body with gzip
400empty batchSend at least one event
400too many events in one batch (max 2000)Split the batch
413body too large, body too large once decompressedKeep each batch under 4 MiB, before and after gzip

429: the monthly quota

A Free organization includes 1,000,000 events a month, for all its projects together. Past that, every batch gets 429 until the next month starts (the 1st, UTC), or until the organization moves to another plan:

{"error":"this organization's free plan includes 1000000 events a month and they're used: upgrade it, or events resume on 1 December","plan":"free","limit":1000000,"used":1000412}
FieldMeaning
errorWhat happened, for a person to read
planThe organization's plan
limitThe events the plan includes each month
usedThe events counted so far this month

Retry-After is the seconds until the next month, but never more than an hour, so an upgrade takes effect soon. Treat it like any other 429: keep the batch and send it again later. The SDKs do this for you, within their queue's limits (see what waits where), and log one warning the first time. The plan field is what tells this 429 apart from the other two: the daily share of one address has source_limit instead, and the rate limit's body has only error.

429: the daily share of one address

With a public key (an ingest or full-access key), one address may send at most a fiftieth of the plan's monthly events in a UTC day, for all the organization's projects together: Free 20,000, Pro 200,000, Business 4,000,000, Unlimited no limit. IPv6 addresses count per /64. Verified batches (a server key, or a valid App Attest or Key Attestation token) aren't limited this way. Past it, batches from that address get 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 is the events one address may send a day. Retry-After is the seconds until the next UTC day, at most an hour. Other addresses keep sending. Treat it like any other 429; if a server gets it, give that server a server key. Why it exists: Verified events.

425: verified events only

A project can accept only verified events from a platform (an owner turns it on in the project's settings; off by default). An unverified batch with an event from that platform gets 425 Too Early, Retry-After: 30 and {"error":"this project accepts only verified events from ios: ...","verification_required":"ios"} (or android). Nothing of the batch is stored. Keep it and send it again, with a valid X-Lyrelog-Attestation token once you have one: the SDKs do this on their own. Verified events.

429: the rate limit

Each project takes at most 60,000 events a minute by default. A batch over it gets 429 with {"error":"rate limit for this project"} and a Retry-After in seconds.

429: unknown keys

An address that sends more than 30 unknown keys in a minute gets 429 with Retry-After: 60. A token that isn't shaped like a Lyrelog key gets 401 straight away.

503

The server can't reach its database or storage right now, or it's busy with other batches. It answers with Retry-After: 5. Retry the same bytes.

Idempotency

Delivery is at least once. When a retry might be a duplicate, resend exactly the same lines: events with the same event_id and ts collapse into one. Never make new ids for a retry.

Apple App Attest

An Apple app on a real iPhone, iPad or Apple Watch can prove it is the project's genuine app, and its events are then stored with verified_by set to app_attest. The Swift SDK is the client (also under React Native and Flutter) and does all of this on its own; this section is for reference. What it proves, and how to set it up: Verified events.

The three routes take a JSON body and the project's ingest key as the bearer, and count toward the project's rate like one event each. They answer 404 until an owner has added an App ID in the project's settings, and 403 to any other key (a server key's events are verified already). They have no CORS: they are for apps, not web pages.

RouteBodyAnswer
POST /v1/attest/challenge{}{"challenge":"..."}: single use, for 5 minutes, for this project only
POST /v1/attest/key{"key_id","attestation","challenge"}{"token","expires_at"}
POST /v1/attest/token{"key_id","assertion","challenge"}{"token","expires_at"}, or 404 for a key the project doesn't have: attest it again
  • key_id is the base64 key id that DCAppAttestService returns; attestation and assertion are base64. The app passes the SHA-256 of the challenge's UTF-8 bytes as clientDataHash.
  • /v1/attest/key is called once per install, with the attestation of a new key. /v1/attest/token renews the token with an assertion made with that key. An attestation or assertion that doesn't check out gets 400.
  • A token is valid for 24 hours. A batch carries it in the X-Lyrelog-Attestation header. A valid one makes the batch verified and spares it the daily share of one address. Without one, nothing changes. One that proves nothing (expired, another project's, or not a token) leaves the batch unverified, and the answer carries X-Lyrelog-Attestation: renew, so the app gets a new one.
  • A batch is never refused because of its token.

Android Key Attestation

An Android app on a real device can prove it is the project's genuine app, signed with your certificate, on a device that hasn't been tampered with. Its events are then stored with verified_by set to key_attestation. The Android SDK is the client (also under React Native and Flutter) and does all of this on its own; this section is for reference. What it proves, and how to set it up: Verified events.

The same rules as App Attest: a JSON body, the project's ingest key as the bearer (403 for any other key), one event of the project's rate each, no CORS, and 404 until an owner has added an Android app (its package and signing certificate) in the project's settings. The challenge comes from the same route, POST /v1/attest/challenge.

RouteBodyAnswer
POST /v1/attest/android/key{"challenge","chain":[...]}{"token","expires_at","key_id"}
POST /v1/attest/android/token{"key_id","challenge","signature"}{"token","expires_at"}, or 404 for a key the project doesn't have: attest it again
  • /v1/attest/android/key is called once per install. The app makes an EC P-256 key in the Android Keystore with the challenge's UTF-8 bytes as its attestation challenge, and sends the key's certificate chain, leaf first, each certificate standard base64 DER. Keep the key_id it answers with.
  • /v1/attest/android/token renews the token: signature is the base64 ECDSA signature (SHA256withECDSA, DER) over a new challenge's UTF-8 bytes, made with that key.
  • A chain or signature that doesn't check out gets 400. Right after the server starts, before it has Google's list of revoked certificates, /v1/attest/android/key may answer 503 with Retry-After: ask again later.
  • Tokens work as App Attest's: 24 hours, in X-Lyrelog-Attestation, renew when one proves nothing, and a batch is never refused because of its token.

CORS

The endpoint answers browsers from any origin, so a web page can send events directly:

HeaderValue
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

The wildcard is safe because no cookies are involved and an ingest key can only append events. The dashboard's own API has no CORS.

Examples

In these examples, the shell variable $LYRELOG_KEY holds one of the project's keys (set it yourself: export LYRELOG_KEY=lyr_srv_...). From a server or a cron job, as here, use a server key, lyr_srv_...; an ingest key, lyr_ing_..., works too, but its events aren't verified.

One 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

Several events, gzipped

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

A rejected line

The second line has a typo, 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 @-

The first line is stored, the second is not:

{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}

Common line errors:

errorWhat to fix
event_id must be a UUID stringSend a UUID such as 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f
ts must carry a time zone (use Z for UTC)2026-11-18T10:00:00Z, not 2026-11-18T10:00:00
message must be a non-empty stringEvery event needs a message
unknown fields: ..., unknown resource fields: ...A typo, or a field Lyrelog doesn't take (also verified_by and country, which only the server sets)
bad attribute name "..." in attrsAn attribute name with a dot or a leading _: nest an object instead
attrs.tags: arrays may only hold stringsArrays in attrs hold strings only
event_id repeated in this batchEach event gets its own id

Health

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

200 {"status":"ok","storage":true,"database":true}, or 503 with "status":"degraded" when the storage or the database is down.