API HTTP
Envía eventos sin SDK. El endpoint de ingesta, cada campo y cada límite, y qué debe hacer un cliente con cada respuesta.
Los SDK usan esta API, y también puede usarla cualquier cosa que hable HTTP. Si esta página y un SDK no coinciden, manda esta página.
El endpoint
POST https://ingest.lyrelog.com/v1/events:batch| Header | Valor |
|---|---|
Authorization | Bearer lyr_ing_... (una clave de ingesta), Bearer lyr_srv_... (una clave de servidor) o una clave de acceso total |
Content-Type | application/x-ndjson (también vale application/jsonl) |
Content-Encoding | gzip (opcional, recomendado), o identity / nada para texto sin comprimir |
X-Lyrelog-Attestation | Opcional. Un token de una app de Apple o Android con una clave de ingesta (consulta Apple App Attest y Android Key Attestation) |
Una clave de lectura no puede enviar eventos: recibe 403. Desde un servidor, usa una clave de
servidor: sus eventos están verificados y no se les aplica la cuota diaria
de una dirección. Las apps y las páginas web usan la clave de ingesta; los eventos de una app de Apple se
pueden verificar con App Attest, y los de una app de Android, con
Key Attestation.
El cuerpo: NDJSON
Un objeto JSON por línea, una línea por evento.
- Como mínimo un evento y como máximo 2.000 líneas por petición. Un cuerpo vacío, o uno con
más líneas, recibe
400para todo el lote. - Como máximo 4 MiB en la red y 4 MiB una vez descomprimido, y 1 MiB por línea (una línea más larga se rechaza por separado).
- Las líneas en blanco se ignoran, pero cuentan en la numeración (así los errores señalan la línea correcta).
{"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"}}Campos
| Campo | Obligatorio | Reglas |
|---|---|---|
event_id | Sí | Un UUID generado una sola vez por evento. Un reenvío con el mismo id y el mismo ts se fusiona en uno. El mismo id dos veces en un lote hace que se rechace la segunda línea. |
ts | Sí | RFC 3339 con zona horaria. Si va hasta un día por delante del servidor, se guarda tal como llega. Si va más adelantado, o es más antiguo que la retención del proyecto, el evento se guarda con la hora de llegada y la hora enviada va en el atributo _lyrelog_ts_clamped. |
level | No | trace, debug, info (por defecto), notice, warning, error, critical |
category | No | Hasta 64 bytes: el área de la app (checkout, sync) |
message | Sí | Hasta 2.048 bytes. Un nombre de evento estable (checkout_done), no una frase. |
user_id | No | Hasta 128 bytes |
install_id | No | Hasta 128 bytes |
session_id | No | Hasta 128 bytes |
attrs | No | Consulta más abajo |
payload | No | Cualquier JSON de hasta 64 KiB una vez serializado. Se guarda comprimido y no se puede buscar en él. |
resource | No | Consulta más abajo |
Los campos desconocidos se rechazan, para que una errata salga a la luz en lugar de perderse.
attrs
Campos pequeños para filtrar y hacer gráficas.
- Valores: cadenas (hasta 1.024 bytes), números, booleanos, null, arrays de cadenas (hasta 64 elementos) y objetos anidados (hasta 4 niveles).
- Como máximo 200 hojas en total.
- Nombres: hasta 128 bytes, sin puntos (anida un objeto en su lugar) y sin
_al principio.
resource
Solo estas claves, cada una de hasta 64 bytes:
app_id, app_version, app_build, os_name, os_version, device_model, locale, sdk,
environment, platform.
environment y platform llevan letras minúsculas, dígitos, - y _, hasta 32 caracteres, y
empiezan por una letra o un dígito. Sin environment, el evento se guarda como production. Sin
platform, el servidor la deduce de sdk y os_name.
Lo que añade el servidor
country: el código ISO de la dirección desde la que llegó el lote, en todos los eventos del lote.
Un cliente no puede fijarlo, y la dirección no se guarda. Consulta Países.
verified_by: server cuando el lote llegó con una clave de servidor, app_attest o
key_attestation cuando llegó con una clave de ingesta y un token válido de
App Attest o de Key Attestation, y vacío en
cualquier otro caso. Un cliente no puede fijarlo: una línea que incluya verified_by se rechaza
con unknown fields: verified_by. Consulta Eventos verificados.
Respuestas
Todas las respuestas son JSON. Un error tiene un campo error que explica qué ha fallado.
| Estado | Significado | Qué hace el cliente |
|---|---|---|
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]} | Guardado. Las líneas rechazadas no son válidas. | Borra el lote. Nunca reenvía las líneas rechazadas. |
400, 413, 415, cualquier otro 4xx | El propio lote está mal | Lo borra: volvería a fallar. |
| 3xx | No es una respuesta de la ingesta: el endpoint está mal | No la sigue; corrige el endpoint. |
401, 403 | Clave desconocida, revocada o de solo lectura | Deja de enviar hasta el siguiente arranque; conserva los datos. |
408, 425, 429, 5xx, error de red | Temporal | Conserva los mismos bytes, reintenta con backoff y respeta Retry-After. |
Un lote se comprueba en este orden: la clave, después Content-Type y el tamaño declarado,
después la cuota mensual, la cuota diaria de una dirección y el límite de frecuencia (todo ello
antes de leer el cuerpo), y por último el cuerpo y sus líneas. Un lote que no pasa una
comprobación recibe esa respuesta y no se guarda nada. Las líneas rechazadas cuentan para el límite
de frecuencia. Los lotes enviados en el mismo instante pueden pasarse un poco de la cuota mensual
antes de que se aplique.
Revocar una clave tiene efecto de inmediato; cuenta con hasta un minuto.
400, 413, 415: el propio lote
| Estado | error | Qué corregir |
|---|---|---|
415 | Content-Type must be application/x-ndjson | Envía application/x-ndjson o application/jsonl |
400 | unsupported Content-Encoding "br" (use gzip) | Envía gzip, o ningún Content-Encoding |
400 | body is not valid gzip | Comprime todo el cuerpo con gzip |
400 | empty batch | Envía al menos un evento |
400 | too many events in one batch (max 2000) | Divide el lote |
413 | body too large, body too large once decompressed | Mantén cada lote por debajo de 4 MiB, antes y después de gzip |
429: la cuota mensual
Una organización Free incluye 1.000.000 de eventos al mes, para todos sus proyectos juntos. A
partir de ahí, cada lote recibe 429 hasta que empiece el mes siguiente (el día 1, UTC) o hasta
que la organización cambie de plan. Una organización Pro con un
límite de gasto recibe lo mismo al llegar a los eventos que
cubre ese límite, con 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}| Campo | Significado |
|---|---|
error | Qué ha pasado, para que lo lea una persona |
limit_kind | plan (los eventos mensuales de Free) o spending_cap (los eventos que cubre el límite de gasto de una organización Pro) |
plan | El plan de la organización |
limit | Los eventos que el plan incluye cada mes, o los que cubre el límite de gasto |
used | Los eventos contados hasta ahora este mes |
Retry-After son los segundos que faltan para el mes siguiente, pero nunca más de una hora, para
que una mejora de plan tenga efecto pronto. Trátalo como cualquier otro 429: conserva el lote y
vuelve a enviarlo más tarde. Los SDK lo hacen por ti, dentro de los límites de su cola (consulta
qué espera y dónde), y registran un aviso la primera vez. El
campo plan es lo que distingue este 429 de los otros dos: la cuota diaria de una dirección
lleva source_limit en su lugar, y el cuerpo del límite de frecuencia solo tiene error.
429: la cuota diaria de una dirección
Con una clave pública (una clave de ingesta o de acceso total), una dirección puede enviar como
máximo una cincuentava parte de los eventos mensuales del plan en un día UTC, para todos los
proyectos de la organización juntos: Free 20.000, Pro 200.000, Business 4.000.000, Unlimited sin
límite. Las direcciones IPv6 cuentan por /64. Los lotes verificados (una clave de servidor, o un
token válido de App Attest o de Key Attestation) no tienen este límite. Al superarlo, los lotes de
esa dirección reciben 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 es el número de eventos que una dirección puede enviar al día. Retry-After son
los segundos que faltan para el siguiente día UTC, como mucho una hora. Las demás direcciones
siguen enviando. Trátalo como cualquier otro 429; si lo recibe un servidor, dale a ese servidor
una clave de servidor. Por qué existe:
Eventos verificados.
425: solo eventos verificados
Un proyecto puede aceptar solo eventos verificados de una plataforma (lo activa un propietario en
los ajustes del proyecto; viene desactivado). Un lote sin verificar con un evento de esa
plataforma recibe 425 Too Early, Retry-After: 30 y
{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}
(o android).
No se guarda nada del lote. Consérvalo y vuelve a enviarlo, con un token
X-Lyrelog-Attestation válido en cuanto lo tengas: los SDK lo hacen por su cuenta.
Eventos verificados.
429: el límite de frecuencia
Cada proyecto admite por defecto como máximo 60.000 eventos por minuto. Un lote que lo supera
recibe 429 con {"error":"rate limit for this project"} y un Retry-After en segundos.
429: claves desconocidas
Una dirección que envía más de 30 claves desconocidas en un minuto recibe 429 con
Retry-After: 60. Un token que no tiene el formato de una clave de Lyrelog recibe 401 directamente.
503
El servidor no puede llegar a su base de datos o a su almacenamiento en este momento, o está
ocupado con otros lotes. Responde con Retry-After: 5. Reintenta con los mismos bytes.
Idempotencia
La entrega es al menos una vez. Cuando un reintento pueda ser un duplicado, reenvía
exactamente las mismas líneas: los eventos con el mismo event_id y el mismo ts se fusionan
en uno. Nunca generes ids nuevos para un reintento.
Apple App Attest
Una app de Apple en un iPhone, iPad o Apple Watch real puede demostrar que es la app auténtica del
proyecto, y entonces sus eventos se guardan con verified_by igual a app_attest. El
SDK de Swift es el cliente (también por debajo de React Native y
Flutter) y hace todo esto por su cuenta; esta sección es de referencia. Qué demuestra y cómo
configurarlo: Eventos verificados.
Las tres rutas reciben un cuerpo JSON y la clave de ingesta del proyecto como bearer, y cada
llamada cuenta como un evento para el límite de frecuencia del proyecto. Responden 404 hasta que
un propietario añade un App ID en los ajustes del proyecto, y 403 a cualquier otra clave (los
eventos de una clave de servidor ya están verificados). No tienen CORS: son para apps, no para
páginas web.
| Ruta | Cuerpo | Respuesta |
|---|---|---|
POST /v1/attest/challenge | {} | {"challenge":"..."}: de un solo uso, durante 5 minutos, solo para este proyecto |
POST /v1/attest/key | {"key_id","attestation","challenge"} | {"token","expires_at"} |
POST /v1/attest/token | {"key_id","assertion","challenge"} | {"token","expires_at"}, o 404 si el proyecto no tiene esa clave: vuelve a atestarla |
key_ides el id de clave en base64 que devuelveDCAppAttestService;attestationyassertionvan en base64. La app pasa el SHA-256 de los bytes UTF-8 del challenge comoclientDataHash./v1/attest/keyse llama una vez por instalación, con la atestación de una clave nueva./v1/attest/tokenrenueva el token con una aserción hecha con esa clave. Una atestación o aserción que no se valida recibe400.- Un token vale durante 24 horas. Un lote lo lleva en el header
X-Lyrelog-Attestation. Uno válido hace que el lote quede verificado y lo libra de la cuota diaria de una dirección. Sin token, no cambia nada. Uno que no demuestra nada (caducado, de otro proyecto o que no es un token) deja el lote sin verificar, y la respuesta llevaX-Lyrelog-Attestation: renewpara que la app consiga uno nuevo. - Un lote nunca se rechaza por su token.
Android Key Attestation
Una app de Android en un dispositivo real puede demostrar que es la app auténtica del proyecto,
firmada con tu certificado, en un dispositivo que no se ha manipulado. Sus eventos se guardan
entonces con verified_by igual a key_attestation. El SDK de Android
es el cliente (también por debajo de React Native y Flutter) y hace todo esto por su cuenta; esta
sección es de referencia. Qué demuestra y cómo configurarlo:
Eventos verificados.
Las mismas reglas que App Attest: un cuerpo JSON, la clave de ingesta del proyecto como bearer
(403 para cualquier otra clave), cada llamada cuenta como un evento para el límite de
frecuencia del proyecto, sin CORS, y 404 hasta que un propietario añade una app de Android (su
paquete y su certificado de firma) en los ajustes del proyecto. El challenge sale de la misma ruta,
POST /v1/attest/challenge.
| Ruta | Cuerpo | Respuesta |
|---|---|---|
POST /v1/attest/android/key | {"challenge","chain":[...]} | {"token","expires_at","key_id"} |
POST /v1/attest/android/token | {"key_id","challenge","signature"} | {"token","expires_at"}, o 404 si el proyecto no tiene esa clave: vuelve a atestarla |
/v1/attest/android/keyse llama una vez por instalación. La app crea una clave EC P-256 en el Android Keystore con los bytes UTF-8 del challenge como challenge de atestación, y envía la cadena de certificados de la clave, empezando por la hoja, cada certificado en DER codificado en base64 estándar. Guarda elkey_idque devuelve./v1/attest/android/tokenrenueva el token:signaturees la firma ECDSA en base64 (SHA256withECDSA, DER) sobre los bytes UTF-8 de un challenge nuevo, hecha con esa clave.- Una cadena o una firma que no se valida recibe
400. Justo después de arrancar el servidor, antes de que tenga la lista de certificados revocados de Google,/v1/attest/android/keypuede responder503conRetry-After: vuelve a pedirlo más tarde. - Los tokens funcionan como los de App Attest: 24 horas, en
X-Lyrelog-Attestation,renewcuando uno no demuestra nada, y un lote nunca se rechaza por su token.
CORS
El endpoint responde a navegadores de cualquier origen, así que una página web puede enviar eventos directamente:
| Header | Valor |
|---|---|
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 |
El comodín es seguro porque no hay cookies de por medio y una clave de ingesta solo puede añadir eventos. La API propia del panel no tiene CORS.
Ejemplos
En estos ejemplos, la variable de shell $LYRELOG_KEY contiene una de las claves del proyecto
(defínela tú: export LYRELOG_KEY=lyr_srv_...). Desde un servidor o un cron job, como aquí, usa
una clave de servidor, lyr_srv_...; una clave de ingesta, lyr_ing_..., también funciona, pero
sus eventos no quedan verificados.
Un evento
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"}}
EOF2Varios eventos, con 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.gzUna línea rechazada
La segunda línea tiene una errata, 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 primera línea se guarda y la segunda no:
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}Errores de línea habituales:
error | Qué corregir |
|---|---|
event_id must be a UUID string | Envía un UUID como 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f |
ts must carry a time zone (use Z for UTC) | 2026-11-18T10:00:00Z, no 2026-11-18T10:00:00 |
message must be a non-empty string | Todo evento necesita un message |
unknown fields: ..., unknown resource fields: ... | Una errata, o un campo que Lyrelog no acepta (también verified_by y country, que solo fija el servidor) |
bad attribute name "..." in attrs | Un nombre de atributo con un punto o con _ al principio: anida un objeto en su lugar |
attrs.tags: arrays may only hold strings | Los arrays de attrs solo admiten cadenas |
event_id repeated in this batch | Cada evento lleva su propio id |
Estado del servicio
GET https://ingest.lyrelog.com/healthz200 {"status":"ok","storage":true,"database":true}, o 503 con "status":"degraded" cuando el
almacenamiento o la base de datos no funcionan.