Enviar um evento

Versão da API 2026-10-affable-towhee

post https://api.getlingara.com/v1/events

Informa ao Lingara o que aconteceu no seu jogo, por exemplo que o aluno entrou num lugar novo. O evento é registado uma única vez e respondido com 202. Com generate: true o Lingara também inicia um plano de aula, que exige lesson_plans:write e tem os mesmos limites e a mesma faturação que POST /v1/lesson-plans: reaction indica o plano, e depois chega lesson_plan.ready ou lesson_plan.failed. Descreva o mundo, nunca o nome ou o chat de um jogador.

Âmbitos events:write

Parâmetros

Lingara-Versionheaderstringopcional: A versão da API com que responder a este pedido. Sem ela, um token de acesso recebe a versão a que o seu cliente está associado, e um pedido sem token recebe a versão atual. A versão ainda em desenvolvimento só é alcançada indicando-a aqui. Uma versão desconhecida responde 400 com o código api_version_unknown. GET /v1/versions lista as versões.
Idempotency-Keyheaderstringobrigatório: Um valor que escolhe para cada evento e reutiliza quando tenta de novo: de 1 a 255 caracteres ASCII visíveis, como um UUID. Uma nova tentativa com a mesma chave recebe a primeira resposta e não é faturada outra vez, mesmo que o conteúdo seja diferente. Sem uma chave válida, o pedido responde 400 com o código idempotency_key_required.

Corpo do pedido `application/json`

typestringobrigatório

dataWorldPracticeRequestedobrigatório

topicstringobrigatório
source_langstringobrigatório
target_langstringobrigatório
levelintegerobrigatório
tagsarray of stringopcional
generateboolean | nullopcional

Respostas

202 O evento está registado

idstringobrigatório

typestringobrigatório

created_atstringobrigatório

reactionReactionReport | nullopcional

statusReactionStatusobrigatório
plan_idstring | nullopcional
plan_statusPlanStatus | nullopcional: O estado do plano quando o evento foi aceite. Só generating promete que chegará lesson_plan.ready ou lesson_plan.failed. Qualquer outro valor é um plano fornecido pela biblioteca, que pode ler já com GET /v1/lesson-plans/{id}.
codestring | nullopcional
errorstring | nullopcional

Erros

402application/json: A chamada de um cliente com faturação por utilização foi recusada antes de gastar o que quer que fosse. spend_cap_reached: o cliente ou a sua conta atingiu o limite de gastos mensal; aumente o limite na página Integrações. metered_billing_inactive: a faturação por utilização não está ativa para esta conta; configure-a ou atualize o método de pagamento na página Integrações.
410application/json: A versão da API com que este pedido é respondido foi descontinuada. Envie uma versão suportada em Lingara-Version, ou associe o cliente a outra versão.
4XXapplication/json: O pedido foi recusado. code indica o motivo e error descreve-o por palavras.
503application/json · text/plain: O serviço está temporariamente indisponível; tente novamente após o número de segundos indicado em Retry-After. Durante a manutenção, o corpo é texto simples em vez do envelope de erro.
5XXapplication/json: O pedido foi recusado. code indica o motivo e error descreve-o por palavras.

codestringobrigatório: O motivo pelo qual o pedido foi recusado, como um código estável para ramificar a lógica: por exemplo insufficient_scope (403), rate_limited (429) e, para um cliente com faturação por utilização, spend_cap_reached (402) e metered_billing_inactive (402).
errorstringobrigatório

Exemplo

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

Prefere uma biblioteca? Veja a secção Bibliotecas.