API HTTP
Envie eventos sem um SDK. O endpoint de ingestão, cada campo e limite, e o que um cliente deve fazer com cada resposta.
Os SDKs usam esta API, e qualquer coisa que fale HTTP também pode usar. Quando esta página e um SDK divergirem, vale o que diz esta página.
O endpoint
POST https://ingest.lyrelog.com/v1/events:batch| Header | Valor |
|---|---|
Authorization | Bearer lyr_ing_... (uma chave de ingestão), Bearer lyr_srv_... (uma chave de servidor) ou uma chave de acesso total |
Content-Type | application/x-ndjson (application/jsonl também funciona) |
Content-Encoding | gzip (opcional, recomendado), ou identity / nenhum para texto simples |
X-Lyrelog-Attestation | Opcional. Um token de um app Apple ou Android com uma chave de ingestão (veja Apple App Attest e Android Key Attestation) |
Uma chave de leitura não pode enviar eventos: recebe 403. A partir de um servidor, use uma chave
de servidor: os eventos dela são verificados e a cota diária de um endereço não
se aplica a eles. Apps e páginas web usam a chave de ingestão; os eventos de um app Apple podem ser
verificados com App Attest, e os de um app Android com
Key Attestation.
O corpo: NDJSON
Um objeto JSON por linha, uma linha por evento.
- No mínimo um evento e no máximo 2.000 linhas por requisição. Um corpo vazio, ou com mais
linhas, recebe
400para o lote inteiro. - No máximo 4 MiB na rede e 4 MiB depois de descomprimido, e 1 MiB por linha (uma linha maior é rejeitada sozinha).
- Linhas em branco são ignoradas, mas continuam contando na numeração das linhas (para que os erros apontem para a linha certa).
{"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 | Obrigatório | Regras |
|---|---|---|
event_id | Sim | Um UUID gerado uma única vez por evento. Um reenvio com o mesmo id e o mesmo ts é deduplicado. O mesmo id duas vezes no mesmo lote faz a segunda linha ser rejeitada. |
ts | Sim | RFC 3339 com fuso horário. Até um dia à frente do servidor, é mantido como foi enviado. Mais à frente que isso, ou mais antigo que a retenção do projeto, o evento é armazenado com a hora de chegada, e a hora enviada vai para o atributo _lyrelog_ts_clamped. |
level | Não | trace, debug, info (padrão), notice, warning, error, critical |
category | Não | Até 64 bytes: a área do app (checkout, sync) |
message | Sim | Até 2.048 bytes. Um nome de evento estável (checkout_done), não um texto livre. |
user_id | Não | Até 128 bytes |
install_id | Não | Até 128 bytes |
session_id | Não | Até 128 bytes |
attrs | Não | Veja abaixo |
payload | Não | Qualquer JSON de até 64 KiB depois de serializado. Armazenado comprimido, não pesquisável. |
resource | Não | Veja abaixo |
Campos desconhecidos são rejeitados, para que um erro de digitação apareça em vez de sumir.
attrs
Campos pequenos para filtrar e montar gráficos.
- Valores: strings (até 1.024 bytes), números, booleanos, null, arrays de strings (até 64 itens) e objetos aninhados (até 4 níveis).
- No máximo 200 folhas no total.
- Nomes: até 128 bytes, sem pontos (aninhe um objeto em vez disso), sem
_no início.
resource
Somente estas chaves, cada uma com até 64 bytes:
app_id, app_version, app_build, os_name, os_version, device_model, locale, sdk,
environment, platform.
environment e platform aceitam letras minúsculas, dígitos, - e _, até 32 caracteres,
começando com uma letra ou um dígito. Sem environment, o evento é armazenado como
production. Sem platform, o servidor deduz uma a partir de sdk e os_name.
Adicionados pelo servidor
country: o código ISO do endereço de onde veio o lote, em todos os eventos do lote. Um cliente
não pode defini-lo, e o endereço não é armazenado. Veja Países.
verified_by: server quando o lote chegou com uma chave de servidor, app_attest ou
key_attestation quando chegou com uma chave de ingestão e um token válido de
App Attest ou Key Attestation, e vazio nos
outros casos. Um cliente não pode defini-lo: uma linha que inclua verified_by é rejeitada com
unknown fields: verified_by. Veja Eventos verificados.
Respostas
Toda resposta é JSON. Um erro tem um campo error que diz o que deu errado.
| Status | Significado | O que o cliente faz |
|---|---|---|
200 {"accepted":n,"rejected":[{"line":i,"error":"..."}]} | Armazenado. As linhas rejeitadas são inválidas. | Apaga o lote. Nunca reenvia as linhas rejeitadas. |
400, 413, 415, qualquer outro 4xx | O próprio lote está errado | Apaga o lote: ele falharia de novo. |
| 3xx | Não é uma resposta da ingestão: o endpoint está errado | Não segue o redirecionamento; corrige o endpoint. |
401, 403 | Chave desconhecida, revogada ou somente leitura | Para de enviar até a próxima inicialização; mantém os dados. |
408, 425, 429, 5xx, erro de rede | Temporário | Mantém os mesmos bytes, tenta de novo com backoff, respeita o Retry-After. |
Um lote é verificado nesta ordem: a chave, depois o Content-Type e o tamanho declarado, depois a
cota mensal, a cota diária de um endereço e o limite de taxa (tudo antes de ler o corpo), e por
fim o corpo e suas linhas. Um lote que falha em uma verificação recebe essa resposta e nada é
armazenado. Linhas rejeitadas contam para o limite de taxa. Lotes enviados no mesmo instante
podem passar um pouco da cota mensal antes de ela ser aplicada.
Revogar uma chave tem efeito imediato; conte com até um minuto.
400, 413, 415: o próprio lote
| Status | error | O que corrigir |
|---|---|---|
415 | Content-Type must be application/x-ndjson | Envie application/x-ndjson ou application/jsonl |
400 | unsupported Content-Encoding "br" (use gzip) | Envie gzip, ou nenhum Content-Encoding |
400 | body is not valid gzip | Comprima o corpo inteiro com gzip |
400 | empty batch | Envie pelo menos um evento |
400 | too many events in one batch (max 2000) | Divida o lote |
413 | body too large, body too large once decompressed | Mantenha cada lote abaixo de 4 MiB, antes e depois do gzip |
429: a cota mensal
Uma organização Free inclui 1.000.000 de eventos por mês, somando todos os seus projetos. Depois
disso, todo lote recebe 429 até o mês seguinte começar (dia 1º, UTC) ou até a organização mudar
de plano. Uma organização Pro com um limite de gastos
recebe o mesmo ao atingir os eventos que o limite cobre, com 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 | O que aconteceu, para uma pessoa ler |
limit_kind | plan (os eventos mensais do Free) ou spending_cap (os eventos que o limite de gastos de uma organização Pro cobre) |
plan | O plano da organização |
limit | Os eventos que o plano inclui por mês, ou que o limite de gastos cobre |
used | Os eventos contados até agora neste mês |
Retry-After traz os segundos até o próximo mês, mas nunca mais de uma hora, para que um upgrade
tenha efeito logo. Trate este 429 como qualquer outro: guarde o lote e envie de novo mais tarde. Os
SDKs fazem isso por você, dentro dos limites da fila deles (veja
o que espera onde), e registram um aviso na primeira vez.
É o campo plan que distingue este 429 dos outros dois: o da cota diária de um endereço traz
source_limit no lugar, e o corpo do limite de taxa tem só error.
429: a cota diária de um endereço
Com uma chave pública (uma chave de ingestão ou de acesso total), um endereço pode enviar no
máximo um cinquenta avos dos eventos mensais do plano em um dia UTC, somando todos os projetos da
organização: Free 20.000, Pro 200.000, Business 4.000.000, Unlimited sem limite. Endereços IPv6
contam por /64. Lotes verificados (uma chave de servidor, ou um token válido de App Attest ou Key
Attestation) não têm esse limite. Passado esse ponto, os lotes desse endereço recebem 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 é o número de eventos que um endereço pode enviar por dia. Retry-After traz os
segundos até o próximo dia UTC, no máximo uma hora. Os outros endereços continuam enviando. Trate
este 429 como qualquer outro; se um servidor o receber, dê a esse servidor uma chave de servidor. Por
que ele existe: Eventos verificados.
425: somente eventos verificados
Um projeto pode aceitar somente eventos verificados de uma plataforma (um proprietário ativa isso
nas configurações do projeto; fica desativado por padrão). Um lote não verificado com um evento dessa
plataforma recebe 425 Too Early, Retry-After: 30 e
{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}
(ou android).
Nada do lote é armazenado. Guarde-o e envie de novo, com um token X-Lyrelog-Attestation válido
assim que tiver um: os SDKs fazem isso sozinhos.
Eventos verificados.
429: o limite de taxa
Por padrão, cada projeto aceita no máximo 60.000 eventos por minuto. Um lote acima disso recebe
429 com {"error":"rate limit for this project"} e um Retry-After em segundos.
429: chaves desconhecidas
Um endereço que envia mais de 30 chaves desconhecidas em um minuto recebe 429 com
Retry-After: 60. Um token que não tem o formato de uma chave do Lyrelog recebe 401 na hora.
503
O servidor não consegue acessar o banco de dados ou o armazenamento no momento, ou está ocupado com
outros lotes. Ele responde com Retry-After: 5. Tente de novo com os mesmos bytes.
Idempotência
A entrega é pelo menos uma vez (at least once). Quando uma nova tentativa pode ser uma duplicata,
reenvie exatamente as mesmas linhas: eventos com o mesmo event_id e o mesmo ts são deduplicados
em um só. Nunca gere ids novos para uma nova tentativa.
Apple App Attest
Um app Apple em um iPhone, iPad ou Apple Watch real pode provar que é o app legítimo do projeto, e
seus eventos passam a ser armazenados com verified_by igual a app_attest. O
SDK de Swift é o cliente (também por baixo de React Native e
Flutter) e faz tudo isso sozinho; esta seção é para referência. O que isso prova, e como
configurar: Eventos verificados.
As três rotas recebem um corpo JSON e a chave de ingestão do projeto como bearer, e cada
chamada conta como um evento na taxa do projeto. Elas respondem 404 até que um proprietário
adicione um App ID nas configurações do projeto, e 403 para qualquer outra chave (os eventos de
uma chave de servidor já são verificados). Elas não têm CORS: são para apps, não para páginas web.
| Rota | Corpo | Resposta |
|---|---|---|
POST /v1/attest/challenge | {} | {"challenge":"..."}: de uso único, válido por 5 minutos, só para este projeto |
POST /v1/attest/key | {"key_id","attestation","challenge"} | {"token","expires_at"} |
POST /v1/attest/token | {"key_id","assertion","challenge"} | {"token","expires_at"}, ou 404 para uma chave que o projeto não tem: faça o attest dela de novo |
key_idé o id da chave em base64 que oDCAppAttestServiceretorna;attestationeassertionestão em base64. O app passa o SHA-256 dos bytes UTF-8 do challenge comoclientDataHash./v1/attest/keyé chamada uma vez por instalação, com o attestation de uma chave nova./v1/attest/tokenrenova o token com uma assertion feita com essa chave. Um attestation ou uma assertion que não passa na verificação recebe400.- Um token vale por 24 horas. O lote leva o token no header
X-Lyrelog-Attestation. Um token válido torna o lote verificado e o livra da cota diária de um endereço. Sem token, nada muda. Um token que não prova nada (expirado, de outro projeto, ou que nem é um token) deixa o lote não verificado, e a resposta trazX-Lyrelog-Attestation: renew, para que o app obtenha um novo. - Um lote nunca é recusado por causa do seu token.
Android Key Attestation
Um app Android em um dispositivo real pode provar que é o app legítimo do projeto, assinado com o
seu certificado, em um dispositivo que não foi adulterado. Seus eventos passam a ser armazenados
com verified_by igual a key_attestation. O SDK de Android é
o cliente (também por baixo de React Native e Flutter) e faz tudo isso sozinho; esta seção é para
referência. O que isso prova, e como configurar:
Eventos verificados.
As mesmas regras do App Attest: um corpo JSON, a chave de ingestão do projeto como bearer
(403 para qualquer outra chave), cada chamada contando como um evento na taxa do projeto, sem CORS, e 404 até
que um proprietário adicione um app Android (o pacote e o certificado de assinatura) nas
configurações do projeto. O challenge vem da mesma rota, POST /v1/attest/challenge.
| Rota | Corpo | Resposta |
|---|---|---|
POST /v1/attest/android/key | {"challenge","chain":[...]} | {"token","expires_at","key_id"} |
POST /v1/attest/android/token | {"key_id","challenge","signature"} | {"token","expires_at"}, ou 404 para uma chave que o projeto não tem: faça o attest dela de novo |
/v1/attest/android/keyé chamada uma vez por instalação. O app cria uma chave EC P-256 no Android Keystore com os bytes UTF-8 do challenge como attestation challenge, e envia a cadeia de certificados da chave, começando pela folha, cada certificado em DER codificado em base64 padrão. Guarde okey_idque vier na resposta./v1/attest/android/tokenrenova o token:signatureé a assinatura ECDSA em base64 (SHA256withECDSA, DER) sobre os bytes UTF-8 de um challenge novo, feita com essa chave.- Uma cadeia ou assinatura que não passa na verificação recebe
400. Logo depois que o servidor inicia, antes de ter a lista de certificados revogados do Google,/v1/attest/android/keypode responder503comRetry-After: tente de novo mais tarde. - Os tokens funcionam como os do App Attest: 24 horas, em
X-Lyrelog-Attestation,renewquando um token não prova nada, e um lote nunca é recusado por causa do seu token.
CORS
O endpoint responde a navegadores de qualquer origem, então uma página web pode enviar eventos diretamente:
| 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 |
O curinga é seguro porque não há cookies envolvidos e uma chave de ingestão só consegue adicionar eventos. A API do próprio painel não tem CORS.
Exemplos
Nestes exemplos, a variável de shell $LYRELOG_KEY guarda uma das chaves do projeto (defina-a
você mesmo: export LYRELOG_KEY=lyr_srv_...). A partir de um servidor ou de um cron job, como
aqui, use uma chave de servidor, lyr_srv_...; uma chave de ingestão, lyr_ing_..., também
funciona, mas os eventos dela não são verificados.
Um 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"}}
EOF2Vários eventos, com 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.gzUma linha rejeitada
A segunda linha tem um erro de digitação, 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 @-A primeira linha é armazenada, a segunda não:
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}Erros de linha comuns:
error | O que corrigir |
|---|---|
event_id must be a UUID string | Envie um UUID como 6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f |
ts must carry a time zone (use Z for UTC) | 2026-11-18T10:00:00Z, não 2026-11-18T10:00:00 |
message must be a non-empty string | Todo evento precisa de um message |
unknown fields: ..., unknown resource fields: ... | Um erro de digitação, ou um campo que o Lyrelog não aceita (inclusive verified_by e country, que só o servidor define) |
bad attribute name "..." in attrs | Um nome de atributo com um ponto ou com _ no início: aninhe um objeto em vez disso |
attrs.tags: arrays may only hold strings | Os arrays em attrs só aceitam strings |
event_id repeated in this batch | Cada evento recebe o seu próprio id |
Saúde
GET https://ingest.lyrelog.com/healthz200 {"status":"ok","storage":true,"database":true}, ou 503 com "status":"degraded" quando
o armazenamento ou o banco de dados está fora do ar.