Enviar un evento

Versión de la API 2026-10-affable-towhee

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

Cuenta a Lingara lo que ha pasado en tu juego, por ejemplo que el alumno entra en un lugar nuevo. El evento se registra una sola vez y se responde con 202. Con generate: true Lingara también empieza un plan de lección, que requiere lesson_plans:write y tiene los mismos límites y la misma facturación que POST /v1/lesson-plans: reaction nombra el plan, y después llega lesson_plan.ready o lesson_plan.failed. Describe el mundo, nunca el nombre ni el chat de un jugador.

Ámbitos events:write

Parámetros

Lingara-Versionheaderstringopcional: La versión de la API con la que se responde a esta solicitud. Sin ella, un token de acceso recibe la versión a la que está vinculado su cliente, y una solicitud sin token recibe la versión actual. La versión aún en desarrollo solo se alcanza nombrándola aquí. Una versión desconocida responde 400 con el código api_version_unknown. GET /v1/versions enumera las versiones.
Idempotency-Keyheaderstringobligatorio: Un valor que eliges para cada evento y reutilizas al reintentarlo: de 1 a 255 caracteres ASCII visibles, como un UUID. Un reintento con la misma clave recibe la primera respuesta y no se vuelve a facturar, aunque su contenido sea distinto. Sin una clave válida, la solicitud responde 400 con el código idempotency_key_required.

Cuerpo de la solicitud `application/json`

typestringobligatorio

dataWorldPracticeRequestedobligatorio

topicstringobligatorio
source_langstringobligatorio
target_langstringobligatorio
levelintegerobligatorio
tagsarray of stringopcional
generateboolean | nullopcional

Respuestas

202 El evento está registrado

idstringobligatorio

typestringobligatorio

created_atstringobligatorio

reactionReactionReport | nullopcional

statusReactionStatusobligatorio
plan_idstring | nullopcional
plan_statusPlanStatus | nullopcional: El estado del plan cuando se aceptó el evento. Solo generating promete que llegará lesson_plan.ready o lesson_plan.failed. Cualquier otro valor es un plan servido desde la biblioteca, que puedes leer ya con GET /v1/lesson-plans/{id}.
codestring | nullopcional
errorstring | nullopcional

Errores

402application/json: Se rechazó la llamada de un cliente con facturación por uso antes de que gastara nada. spend_cap_reached: el cliente o su cuenta ha alcanzado su límite de gasto mensual; sube el límite en la página Integraciones. metered_billing_inactive: la facturación por uso no está activa para esta cuenta; configúrala o actualiza el método de pago en la página Integraciones.
410application/json: La versión de la API con la que se responde a esta solicitud se ha retirado. Envía una versión admitida en Lingara-Version o vincula el cliente a otra versión.
4XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.
503application/json · text/plain: El servicio no está disponible temporalmente; vuelve a intentarlo tras el número de segundos indicado en Retry-After. Durante el mantenimiento, el cuerpo es texto sin formato en lugar del sobre de error.
5XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.

codestringobligatorio: Por qué se rechazó la solicitud, como un código estable con el que ramificar: por ejemplo insufficient_scope (403), rate_limited (429) y, para un cliente con facturación por uso, spend_cap_reached (402) y metered_billing_inactive (402).
errorstringobligatorio

Ejemplo

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}}'

¿Prefieres una biblioteca? Consulta la sección Bibliotecas.