Riferimento dell'API di Lingara

Versione API 2026-10-affable-towhee

Genera elenchi di vocaboli e piani di lezione, e conversa con il tutor, nelle lingue insegnate da Lingara. Ogni chiamata è pagata dal client che la effettua: un client allowance consuma la quota del suo proprietario, e a un client metered viene fatturato il suo utilizzo.

Preferisci una libreria? Vedi la sezione Librerie.

URL di base https://api.getlingara.com

Un token di accesso OAuth 2.0, inviato come Authorization: Bearer <token>. Un server che agisce per conto proprio scambia l'id e il secret del suo client all'URL del token (client_credentials). Un'app che agisce per conto di un utente Lingara che dà il consenso usa il codice di autorizzazione (authorization_code) e poi aggiorna il token. Un token vale un'ora. Ogni operazione richiede uno scope.

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

Scope
`vocab:generate`	Generare elenchi di vocaboli.	Genera un elenco di vocaboli
`lesson_plans:read`	Leggere i tuoi piani di lezione e riconnettersi al loro avanzamento.	Ottieni un piano di lezione Riconnettiti a un piano di lezione
`lesson_plans:write`	Creare piani di lezione.	Crea un piano di lezione
`tutor:converse`	Conversare con il tutor. Richiede un piano a pagamento.	Invia un turno al tutor
`usage:read`	Vedere la quota rimanente, o l'utilizzo di un client `metered` in questo mese.	Ottieni la quota rimanente
`events:read`	Leggere gli eventi relativi al tuo account e registrare gli endpoint che li ricevono.	Elenca gli eventi Trasmetti gli eventi
`events:write`	Inviare eventi a Lingara dal tuo gioco o dalla tua integrazione.	Invia un evento

Errori

402application/json: La chiamata di un client con fatturazione a consumo è stata rifiutata prima che spendesse qualcosa. spend_cap_reached: il client o il suo account ha raggiunto il limite di spesa mensile; alza il limite nella pagina Integrazioni. metered_billing_inactive: la fatturazione a consumo non è attiva per questo account; configurala o aggiorna il metodo di pagamento nella pagina Integrazioni.
410application/json: La versione dell'API con cui si risponde a questa richiesta è stata dismessa. Invia una versione supportata in Lingara-Version, oppure associa il client a un'altra versione.
4XXapplication/json: La richiesta è stata rifiutata. code dice il motivo, e error lo spiega a parole.
503application/json · text/plain: Il servizio è temporaneamente non disponibile; riprova dopo il numero di secondi indicato in Retry-After. Durante la manutenzione il corpo è testo semplice anziché l'envelope di errore.
5XXapplication/json: La richiesta è stata rifiutata. code dice il motivo, e error lo spiega a parole.

codestringobbligatorio: Perché la richiesta è stata rifiutata, come codice stabile su cui diramare la logica: per esempio insufficient_scope (403), rate_limited (429) e, per un client con fatturazione a consumo, spend_cap_reached (402) e metered_billing_inactive (402).
errorstringobbligatorio

Vocaboli

Genera elenchi di vocaboli al livello dello studente.

Genera un elenco di vocaboli POST /v1/vocab/stream

Piani di lezione

Crea piani di lezione, leggili e riconnettiti a uno ancora in generazione.

Crea un piano di lezione POST /v1/lesson-plans
Ottieni un piano di lezione GET /v1/lesson-plans/{id}
Riconnettiti a un piano di lezione GET /v1/lesson-plans/{id}/stream

Tutor

Conversa con il tutor di lingua, un turno alla volta.

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

Eventi

Leggi gli eventi che accadono nel tuo account, pagina per pagina o come flusso.

Elenca gli eventi GET /v1/events
Invia un evento POST /v1/events
Trasmetti gli eventi GET /v1/events/stream

Account

Scopri quanta quota ti resta.

Ottieni la quota rimanente GET /v1/usage

Riferimento

Questo documento, in formato leggibile dalle macchine.

Ottieni questo documento GET /v1/openapi.json
Ottieni il documento degli eventi GET /v1/asyncapi.json
Elenca le versioni dell'API GET /v1/versions
Ottieni una versione dell'API GET /v1/versions/{id}

Catalogo degli eventi

Lingara registra come eventi ciò che accade ai piani di lezione e all'utilizzo del tuo account, e accetta eventi dal tuo gioco o dalla tua app. Ogni evento, comunque viaggi, ha la stessa busta, e il catalogo degli eventi li elenca tutti. Webhook ed eventi

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

Tu → Lingara world.context_changed
Tu → Lingara world.practice_requested

In caso di discrepanza tra una traduzione e il riferimento in inglese, fa fede il riferimento in inglese.