Referência da API do Lingara

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

Gere listas de vocabulário e planos de aula, e mantenha conversas com o tutor, nas línguas que o Lingara ensina. Cada chamada é paga pelo cliente que a faz: um cliente allowance consome a quota do seu proprietário, e um cliente metered é faturado pela sua utilização.

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

URL base https://api.getlingara.com

Um token de acesso OAuth 2.0, enviado como Authorization: Bearer <token>. Um servidor que age em nome próprio troca o id e o segredo do seu cliente no URL do token (client_credentials). Uma aplicação que age em nome de um utilizador Lingara que dá o seu consentimento usa o código de autorização (authorization_code) e depois renova o token. Um token é válido durante uma hora. Cada operação precisa de um âmbito.

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

Âmbitos
`vocab:generate`	Gerar listas de vocabulário.	Gerar uma lista de vocabulário
`lesson_plans:read`	Consultar os seus planos de aula e voltar a ligar-se ao seu progresso.	Obter um plano de aula Voltar a ligar-se a um plano de aula
`lesson_plans:write`	Criar planos de aula.	Criar um plano de aula
`tutor:converse`	Manter conversas com o tutor. Requer um plano pago.	Enviar uma mensagem ao tutor
`usage:read`	Ver a sua quota restante, ou a utilização de um cliente `metered` este mês.	Obter a sua quota restante
`events:read`	Ler eventos sobre a sua conta e registar endpoints que os recebem.	Listar eventos Transmitir eventos
`events:write`	Enviar eventos do seu jogo ou integração para o Lingara.	Enviar um evento

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

Vocabulário

Gere listas de vocabulário ao nível de um aluno.

Gerar uma lista de vocabulário POST /v1/vocab/stream

Planos de aula

Crie planos de aula, consulte-os e volte a ligar-se a um que ainda esteja a ser gerado.

Criar um plano de aula POST /v1/lesson-plans
Obter um plano de aula GET /v1/lesson-plans/{id}
Voltar a ligar-se a um plano de aula GET /v1/lesson-plans/{id}/stream

Tutor

Mantenha uma conversa com o tutor de línguas, uma vez de cada vez.

Enviar uma mensagem ao tutor POST /v1/tutor/message

Eventos

Leia os eventos que acontecem na sua conta, página a página ou como um fluxo.

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

Conta

Veja quanto lhe resta da sua quota.

Obter a sua quota restante GET /v1/usage

Referência

Este documento, num formato legível por máquina.

Obter este documento GET /v1/openapi.json
Obter o documento de eventos GET /v1/asyncapi.json
Listar as versões da API GET /v1/versions
Obter uma versão da API GET /v1/versions/{id}

Catálogo de eventos

O Lingara regista como eventos o que acontece aos planos de aula e à utilização da sua conta, e aceita eventos do seu jogo ou aplicação. Cada evento, seja qual for o caminho por onde viaja, tem o mesmo envelope, e o catálogo de eventos lista-os todos. Webhooks e eventos

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

Você → Lingara world.context_changed
Você → Lingara world.practice_requested

Se uma tradução e a referência em inglês divergirem, prevalece a referência em inglês.