Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

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
HeaderValor
AuthorizationBearer lyr_ing_... (uma chave de ingestão), Bearer lyr_srv_... (uma chave de servidor) ou uma chave de acesso total
Content-Typeapplication/x-ndjson (application/jsonl também funciona)
Content-Encodinggzip (opcional, recomendado), ou identity / nenhum para texto simples
X-Lyrelog-AttestationOpcional. 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 400 para 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

CampoObrigatórioRegras
event_idSimUm 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.
tsSimRFC 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.
levelNãotrace, debug, info (padrão), notice, warning, error, critical
categoryNãoAté 64 bytes: a área do app (checkout, sync)
messageSimAté 2.048 bytes. Um nome de evento estável (checkout_done), não um texto livre.
user_idNãoAté 128 bytes
install_idNãoAté 128 bytes
session_idNãoAté 128 bytes
attrsNãoVeja abaixo
payloadNãoQualquer JSON de até 64 KiB depois de serializado. Armazenado comprimido, não pesquisável.
resourceNãoVeja 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.

StatusSignificadoO 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 4xxO próprio lote está erradoApaga o lote: ele falharia de novo.
3xxNão é uma resposta da ingestão: o endpoint está erradoNão segue o redirecionamento; corrige o endpoint.
401, 403Chave desconhecida, revogada ou somente leituraPara de enviar até a próxima inicialização; mantém os dados.
408, 425, 429, 5xx, erro de redeTemporárioManté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

StatuserrorO que corrigir
415Content-Type must be application/x-ndjsonEnvie application/x-ndjson ou application/jsonl
400unsupported Content-Encoding "br" (use gzip)Envie gzip, ou nenhum Content-Encoding
400body is not valid gzipComprima o corpo inteiro com gzip
400empty batchEnvie pelo menos um evento
400too many events in one batch (max 2000)Divida o lote
413body too large, body too large once decompressedMantenha 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}
CampoSignificado
errorO que aconteceu, para uma pessoa ler
limit_kindplan (os eventos mensais do Free) ou spending_cap (os eventos que o limite de gastos de uma organização Pro cobre)
planO plano da organização
limitOs eventos que o plano inclui por mês, ou que o limite de gastos cobre
usedOs 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.

RotaCorpoResposta
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 o DCAppAttestService retorna; attestation e assertion estão em base64. O app passa o SHA-256 dos bytes UTF-8 do challenge como clientDataHash.
  • /v1/attest/key é chamada uma vez por instalação, com o attestation de uma chave nova. /v1/attest/token renova o token com uma assertion feita com essa chave. Um attestation ou uma assertion que não passa na verificação recebe 400.
  • 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 traz X-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.

RotaCorpoResposta
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 o key_id que vier na resposta.
  • /v1/attest/android/token renova 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/key pode responder 503 com Retry-After: tente de novo mais tarde.
  • Os tokens funcionam como os do App Attest: 24 horas, em X-Lyrelog-Attestation, renew quando 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:

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

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

Vá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.gz

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

errorO que corrigir
event_id must be a UUID stringEnvie 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 stringTodo 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 attrsUm nome de atributo com um ponto ou com _ no início: aninhe um objeto em vez disso
attrs.tags: arrays may only hold stringsOs arrays em attrs só aceitam strings
event_id repeated in this batchCada evento recebe o seu próprio id

Saúde

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

200 {"status":"ok","storage":true,"database":true}, ou 503 com "status":"degraded" quando o armazenamento ou o banco de dados está fora do ar.