Referencia de la API de Lingara

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

Genera listas de vocabulario y planes de lección, y mantén conversaciones con el tutor, en los idiomas que enseña Lingara. Cada llamada la paga el cliente que la hace: un cliente allowance consume la cuota de su propietario y a un cliente metered se le factura su uso.

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

URL base https://api.getlingara.com

Un token de acceso OAuth 2.0, enviado como Authorization: Bearer <token>. Un servidor que actúa en su propio nombre intercambia el id y el secreto de su cliente en la URL de token (client_credentials). Una aplicación que actúa en nombre de un usuario de Lingara que da su consentimiento usa el código de autorización (authorization_code) y después renueva el token. Un token dura una hora. Cada operación necesita un ámbito.

URL del token https://api.getlingara.com/oauth/token

Ámbitos
`vocab:generate`	Generar listas de vocabulario.	Generar una lista de vocabulario
`lesson_plans:read`	Leer tus planes de lección y reconectarte a su progreso.	Obtener un plan de lección Reconectarse a un plan de lección
`lesson_plans:write`	Crear planes de lección.	Crear un plan de lección
`tutor:converse`	Mantener conversaciones con el tutor. Requiere un plan de pago.	Enviar un turno al tutor
`usage:read`	Consultar tu cuota restante, o el uso de un cliente `metered` este mes.	Obtener tu cuota restante
`events:read`	Leer eventos sobre tu cuenta y registrar endpoints que los reciban.	Listar eventos Transmitir eventos
`events:write`	Enviar eventos desde tu juego o integración a Lingara.	Enviar un evento

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

Vocabulario

Genera listas de vocabulario al nivel del estudiante.

Generar una lista de vocabulario POST /v1/vocab/stream

Planes de lección

Crea planes de lección, consúltalos y vuelve a conectarte a uno que aún se está generando.

Crear un plan de lección POST /v1/lesson-plans
Obtener un plan de lección GET /v1/lesson-plans/{id}
Reconectarse a un plan de lección GET /v1/lesson-plans/{id}/stream

Tutor

Mantén una conversación con el tutor de idiomas, un turno cada vez.

Enviar un turno al tutor POST /v1/tutor/message

Eventos

Lee los eventos que ocurren en tu cuenta, página a página o como un flujo.

Listar eventos GET /v1/events
Enviar un evento POST /v1/events
Transmitir eventos GET /v1/events/stream

Cuenta

Consulta cuánta cuota te queda.

Obtener tu cuota restante GET /v1/usage

Referencia

Este documento, en formato legible por máquina.

Obtener este documento GET /v1/openapi.json
Obtener el documento de eventos GET /v1/asyncapi.json
Listar las versiones de la API GET /v1/versions
Obtener una versión de la API GET /v1/versions/{id}

Catálogo de eventos

Lingara registra como eventos lo que ocurre con los planes de lección y el uso de tu cuenta, y acepta eventos de tu juego o aplicación. Cada evento, viaje por donde viaje, tiene el mismo sobre, y el catálogo de eventos los enumera todos. Webhooks y eventos

Lingara → tú lesson_plan.ready
Lingara → tú lesson_plan.failed
Lingara → tú usage.threshold_reached
Lingara → tú webhook.test
Lingara → tú app.installed
Lingara → tú app.uninstalled

Tú → Lingara world.context_changed
Tú → Lingara world.practice_requested

Si una traducción y la referencia en inglés difieren, prevalece la referencia en inglés.