Send an event

API version 2026-10-affable-towhee

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

Tells Lingara what happened in your game, such as the learner entering a new place. The event is recorded once and answered with 202. With generate: true Lingara also starts a lesson plan, which needs lesson_plans:write and is limited and billed like POST /v1/lesson-plans: reaction names the plan, and lesson_plan.ready or lesson_plan.failed follows. Describe the world, never a player's name or chat.

Scopes events:write

Parameters

Lingara-Versionheaderstringoptional: The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers 400 with code api_version_unknown. GET /v1/versions lists the versions.
Idempotency-Keyheaderstringrequired: A value you choose for each event and reuse when you retry it: 1 to 255 visible ASCII characters, such as a UUID. A retry with the same key gets the first answer back and is not billed again, even if its body differs. Without a valid key the request answers 400 with code idempotency_key_required.

Request body `application/json`

typestringrequired

dataWorldPracticeRequestedrequired

topicstringrequired
source_langstringrequired
target_langstringrequired
levelintegerrequired
tagsarray of stringoptional
generateboolean | nulloptional

Responses

202 The event is recorded

idstringrequired

typestringrequired

created_atstringrequired

reactionReactionReport | nulloptional

statusReactionStatusrequired
plan_idstring | nulloptional
plan_statusPlanStatus | nulloptional: The plan's status when the event was accepted. Only generating promises that lesson_plan.ready or lesson_plan.failed will follow. Any other value is a plan served from the library, which you can read now with GET /v1/lesson-plans/{id}.
codestring | nulloptional
errorstring | nulloptional

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

Example

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