Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

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
HeaderValor
AuthorizationBearer lyr_ing_... (una clave de ingesta), Bearer lyr_srv_... (una clave de servidor) o una clave de acceso total
Content-Typeapplication/x-ndjson (también vale application/jsonl)
Content-Encodinggzip (opcional, recomendado), o identity / nada para texto sin comprimir
X-Lyrelog-AttestationOpcional. 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 400 para 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

CampoObligatorioReglas
event_idSí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.
tsSí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.
levelNotrace, debug, info (por defecto), notice, warning, error, critical
categoryNoHasta 64 bytes: el área de la app (checkout, sync)
messageSíHasta 2.048 bytes. Un nombre de evento estable (checkout_done), no una frase.
user_idNoHasta 128 bytes
install_idNoHasta 128 bytes
session_idNoHasta 128 bytes
attrsNoConsulta más abajo
payloadNoCualquier JSON de hasta 64 KiB una vez serializado. Se guarda comprimido y no se puede buscar en él.
resourceNoConsulta 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.

EstadoSignificadoQué 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 4xxEl propio lote está malLo borra: volvería a fallar.
3xxNo es una respuesta de la ingesta: el endpoint está malNo la sigue; corrige el endpoint.
401, 403Clave desconocida, revocada o de solo lecturaDeja de enviar hasta el siguiente arranque; conserva los datos.
408, 425, 429, 5xx, error de redTemporalConserva 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

EstadoerrorQué corregir
415Content-Type must be application/x-ndjsonEnvía application/x-ndjson o application/jsonl
400unsupported Content-Encoding "br" (use gzip)Envía gzip, o ningún Content-Encoding
400body is not valid gzipComprime todo el cuerpo con gzip
400empty batchEnvía al menos un evento
400too many events in one batch (max 2000)Divide el lote
413body too large, body too large once decompressedManté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}
CampoSignificado
errorQué ha pasado, para que lo lea una persona
limit_kindplan (los eventos mensuales de Free) o spending_cap (los eventos que cubre el límite de gasto de una organización Pro)
planEl plan de la organización
limitLos eventos que el plan incluye cada mes, o los que cubre el límite de gasto
usedLos 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.

RutaCuerpoRespuesta
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_id es el id de clave en base64 que devuelve DCAppAttestService; attestation y assertion van en base64. La app pasa el SHA-256 de los bytes UTF-8 del challenge como clientDataHash.
  • /v1/attest/key se llama una vez por instalación, con la atestación de una clave nueva. /v1/attest/token renueva el token con una aserción hecha con esa clave. Una atestación o aserción que no se valida recibe 400.
  • 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 lleva X-Lyrelog-Attestation: renew para 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.

RutaCuerpoRespuesta
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/key se 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 el key_id que devuelve.
  • /v1/attest/android/token renueva el token: signature es 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/key puede responder 503 con Retry-After: vuelve a pedirlo más tarde.
  • Los tokens funcionan como los de App Attest: 24 horas, en X-Lyrelog-Attestation, renew cuando 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:

HeaderValor
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

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

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

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

errorQué corregir
event_id must be a UUID stringEnví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 stringTodo 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 attrsUn nombre de atributo con un punto o con _ al principio: anida un objeto en su lugar
attrs.tags: arrays may only hold stringsLos arrays de attrs solo admiten cadenas
event_id repeated in this batchCada evento lleva su propio id

Estado del servicio

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

200 {"status":"ok","storage":true,"database":true}, o 503 con "status":"degraded" cuando el almacenamiento o la base de datos no funcionan.