Een gebeurtenis versturen

API-versie 2026-10-affable-towhee

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

Vertelt Lingara wat er in je game is gebeurd, bijvoorbeeld dat de leerling een nieuwe plek binnengaat. De gebeurtenis wordt één keer vastgelegd en beantwoord met 202. Met generate: true start Lingara ook een lesplan, waarvoor lesson_plans:write nodig is en dat net als POST /v1/lesson-plans wordt begrensd en gefactureerd: reaction noemt het plan, daarna volgt lesson_plan.ready of lesson_plan.failed. Beschrijf de wereld, nooit de naam of chat van een speler.

Bevoegdheden events:write

Parameters

Lingara-Versionheaderstringoptioneel: De API-versie waaronder dit verzoek wordt beantwoord. Zonder deze krijgt een toegangstoken de versie waaraan zijn client is gekoppeld, en een verzoek zonder token de huidige versie. De versie die nog in ontwikkeling is, bereik je alleen door die hier te noemen. Een onbekende versie geeft 400 met code api_version_unknown. GET /v1/versions toont de versies.
Idempotency-Keyheaderstringverplicht: Een waarde die je voor elke gebeurtenis kiest en opnieuw meestuurt als je het nog eens probeert: 1 tot 255 zichtbare ASCII-tekens, zoals een UUID. Een nieuwe poging met dezelfde sleutel krijgt het eerste antwoord terug en wordt niet opnieuw gefactureerd, ook als de inhoud verschilt. Zonder geldige sleutel antwoordt het verzoek 400 met code idempotency_key_required.

Request-body `application/json`

typestringverplicht

dataWorldPracticeRequestedverplicht

topicstringverplicht
source_langstringverplicht
target_langstringverplicht
levelintegerverplicht
tagsarray of stringoptioneel
generateboolean | nulloptioneel

Antwoorden

202 De gebeurtenis is vastgelegd

idstringverplicht

typestringverplicht

created_atstringverplicht

reactionReactionReport | nulloptioneel

statusReactionStatusverplicht
plan_idstring | nulloptioneel
plan_statusPlanStatus | nulloptioneel: De status van het plan toen de gebeurtenis werd geaccepteerd. Alleen generating belooft dat lesson_plan.ready of lesson_plan.failed volgt. Elke andere waarde is een plan uit de bibliotheek, dat je nu kunt lezen met GET /v1/lesson-plans/{id}.
codestring | nulloptioneel
errorstring | nulloptioneel

Fouten

402application/json: De aanroep van een client met verbruiksafrekening is geweigerd voordat die iets heeft uitgegeven. spend_cap_reached: de client of zijn account heeft zijn maandelijkse uitgavenlimiet bereikt; verhoog de limiet op de pagina Integraties. metered_billing_inactive: verbruiksafrekening is niet actief voor dit account; stel die in of werk de betaalmethode bij op de pagina Integraties.
410application/json: De API-versie waaronder dit verzoek wordt beantwoord, is stopgezet. Stuur een ondersteunde versie mee in Lingara-Version, of koppel de client aan een andere versie.
4XXapplication/json: Het verzoek is geweigerd. code geeft de reden aan en error beschrijft die in woorden.
503application/json · text/plain: De dienst is tijdelijk niet beschikbaar; probeer het opnieuw na het aantal seconden in Retry-After. Tijdens onderhoud is de body platte tekst in plaats van de foutenvelop.
5XXapplication/json: Het verzoek is geweigerd. code geeft de reden aan en error beschrijft die in woorden.

codestringverplicht: Waarom het verzoek is geweigerd, als stabiele code om op te vertakken: bijvoorbeeld insufficient_scope (403), rate_limited (429) en, voor een client met verbruiksafrekening, spend_cap_reached (402) en metered_billing_inactive (402).
errorstringverplicht

Voorbeeld

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

Liever een bibliotheek? Zie de sectie Bibliotheken.