Lingara API reference

API version 2026-10-affable-towhee

Generate vocabulary lists and lesson plans, and hold tutor conversations, in the languages Lingara teaches. Each call is paid for by the client that makes it: an allowance client spends its owner's allowance, and a metered client is billed for its usage.

Prefer a library? See the Libraries section.

Base URL https://api.getlingara.com

An OAuth 2.0 access token, sent as Authorization: Bearer <token>. A server acting as itself exchanges its client's id and secret at the token URL (client_credentials). An app acting for a Lingara user who consents uses the authorization code (authorization_code) and then refreshes. A token lasts one hour. Each operation needs one scope.

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

Scopes
`vocab:generate`	Generate vocabulary lists.	Generate a vocabulary list
`lesson_plans:read`	Read your lesson plans and reconnect to their progress.	Get a lesson plan Reconnect to a lesson plan
`lesson_plans:write`	Create lesson plans.	Create a lesson plan
`tutor:converse`	Hold tutor conversations. Requires a paid plan.	Send a tutor turn
`usage:read`	See your remaining allowance, or a `metered` client's usage this month.	Get your remaining allowance
`events:read`	Read events about your account, and register endpoints that receive them.	List events Stream events
`events:write`	Send events from your game or integration to Lingara.	Send an event

Errors

402application/json: A metered client's call was refused before it spent anything. spend_cap_reached: the client or its account has reached its monthly spending limit; raise the limit on the Integrations page. metered_billing_inactive: usage billing is not active for this account; set it up, or update the payment method, on the Integrations page.
410application/json: The API version this request is answered under has been discontinued. Send a supported version in Lingara-Version, or re-pin the client.
4XXapplication/json: The request was refused. code says why, and error says it in words.
503application/json · text/plain: The service is temporarily unavailable; retry after the number of seconds in Retry-After. During maintenance the body is plain text rather than the error envelope.
5XXapplication/json: The request was refused. code says why, and error says it in words.

codestringrequired: Why the request was refused, as a stable code to branch on: for example insufficient_scope (403), rate_limited (429) and, for a metered client, spend_cap_reached (402) and metered_billing_inactive (402).
errorstringrequired

Vocabulary

Generate vocabulary lists at a learner's level.

Generate a vocabulary list POST /v1/vocab/stream

Lesson plans

Create lesson plans, read them, and reconnect to one that is still generating.

Create a lesson plan POST /v1/lesson-plans
Get a lesson plan GET /v1/lesson-plans/{id}
Reconnect to a lesson plan GET /v1/lesson-plans/{id}/stream

Tutor

Hold a conversation with the language tutor, one turn at a time.

Send a tutor turn POST /v1/tutor/message

Events

Read the events that happen in your account, page by page or as a stream.

List events GET /v1/events
Send an event POST /v1/events
Stream events GET /v1/events/stream

Account

See how much of your allowance is left.

Get your remaining allowance GET /v1/usage

Reference

This document, in machine-readable form.

Get this document GET /v1/openapi.json
Get the events document GET /v1/asyncapi.json
List API versions GET /v1/versions
Get an API version GET /v1/versions/{id}

Event catalogue

Lingara records what happens to your account's lesson plans and usage as events, and accepts events from your game or app. Every event, whichever way it travels, has the same envelope, and the event catalogue lists them all. Webhooks and events

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

You → Lingara world.context_changed
You → Lingara world.practice_requested