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| Header | Value |
|---|---|
Authorization | Bearer lyr_ing_... (an ingest key), Bearer lyr_srv_... (a server key), or a full-access key |
Content-Type | application/x-ndjson (application/jsonl works too) |
Content-Encoding | gzip (optional, recommended), or identity / none for plain text |
X-Lyrelog-Attestation | Optional. 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
400for 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
| Field | Required | Rules |
|---|---|---|
event_id | Yes | A 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. |
ts | Yes | RFC 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. |
level | No | trace, debug, info (default), notice, warning, error, critical |
category | No | Up to 64 bytes: the area of the app (checkout, sync) |
message | Yes | Up to 2,048 bytes. A stable event name (checkout_done), not prose. |
user_id | No | Up to 128 bytes |
install_id | No | Up to 128 bytes |
session_id | No | Up to 128 bytes |
attrs | No | See below |
payload | No | Any JSON up to 64 KiB once serialized. Stored compressed, not searchable. |
resource | No | See 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.
| Status | Meaning | What 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 4xx | The batch itself is wrong | Delete it: it would fail again. |
| 3xx | Not an answer from the ingest: the endpoint is wrong | Don't follow it; fix the endpoint. |
401, 403 | Unknown, revoked or read-only key | Stop sending until the next launch; keep the data. |
408, 425, 429, 5xx, network error | Temporary | Keep 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
| Status | error | What to fix |
|---|---|---|
415 | Content-Type must be application/x-ndjson | Send application/x-ndjson or application/jsonl |
400 | unsupported Content-Encoding "br" (use gzip) | Send gzip, or no Content-Encoding |
400 | body is not valid gzip | Compress the whole body with gzip |
400 | empty batch | Send at least one event |
400 | too many events in one batch (max 2000) | Split the batch |
413 | body too large, body too large once decompressed | Keep 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}| Field | Meaning |
|---|---|
error | What happened, for a person to read |
plan | The organization's plan |
limit | The events the plan includes each month |
used | The 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.
| Route | Body | Answer |
|---|---|---|
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_idis the base64 key id thatDCAppAttestServicereturns;attestationandassertionare base64. The app passes the SHA-256 of the challenge's UTF-8 bytes asclientDataHash./v1/attest/keyis called once per install, with the attestation of a new key./v1/attest/tokenrenews the token with an assertion made with that key. An attestation or assertion that doesn't check out gets400.- A token is valid for 24 hours. A batch carries it in the
X-Lyrelog-Attestationheader. 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 carriesX-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.
| Route | Body | Answer |
|---|---|---|
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/keyis 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 thekey_idit answers with./v1/attest/android/tokenrenews the token:signatureis 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/keymay answer503withRetry-After: ask again later. - Tokens work as App Attest's: 24 hours, in
X-Lyrelog-Attestation,renewwhen 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:
| Header | Value |
|---|---|
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 |
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"}}
EOF2Several 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.gzA 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:
error | What to fix |
|---|---|
event_id must be a UUID string | Send 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 string | Every 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 attrs | An attribute name with a dot or a leading _: nest an object instead |
attrs.tags: arrays may only hold strings | Arrays in attrs hold strings only |
event_id repeated in this batch | Each event gets its own id |
Health
GET https://ingest.lyrelog.com/healthz200 {"status":"ok","storage":true,"database":true}, or 503 with "status":"degraded" when
the storage or the database is down.