Ereignis senden

API-Version 2026-10-affable-towhee

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

Teilt Lingara mit, was in Ihrem Spiel geschehen ist, etwa dass die lernende Person einen neuen Ort betritt. Das Ereignis wird einmal gespeichert und mit 202 beantwortet. Mit generate: true startet Lingara außerdem einen Lektionsplan; dafür ist lesson_plans:write nötig, und Limits und Abrechnung gelten wie bei POST /v1/lesson-plans: reaction nennt den Plan, danach folgt lesson_plan.ready oder lesson_plan.failed. Beschreiben Sie die Welt, niemals den Namen oder Chat einer spielenden Person.

Scopes events:write

Parameter

Lingara-Versionheaderstringoptional: Die API-Version, unter der diese Anfrage beantwortet wird. Ohne sie erhält ein Zugriffstoken die Version, an die sein Client gebunden ist, und eine Anfrage ohne Token die aktuelle Version. Die Version in Entwicklung ist nur erreichbar, indem man sie hier nennt. Eine unbekannte Version wird mit 400 und dem Code api_version_unknown beantwortet. GET /v1/versions listet die Versionen auf.
Idempotency-Keyheaderstringerforderlich: Ein Wert, den Sie für jedes Ereignis wählen und bei einer Wiederholung erneut senden: 1 bis 255 sichtbare ASCII-Zeichen, etwa eine UUID. Eine Wiederholung mit demselben Schlüssel erhält die erste Antwort zurück und wird nicht erneut abgerechnet, auch wenn ihr Inhalt abweicht. Ohne gültigen Schlüssel antwortet die Anfrage mit 400 und dem Code idempotency_key_required.

Anfragetext `application/json`

typestringerforderlich

dataWorldPracticeRequestederforderlich

topicstringerforderlich
source_langstringerforderlich
target_langstringerforderlich
levelintegererforderlich
tagsarray of stringoptional
generateboolean | nulloptional

Antworten

202 Das Ereignis ist gespeichert

idstringerforderlich

typestringerforderlich

created_atstringerforderlich

reactionReactionReport | nulloptional

statusReactionStatuserforderlich
plan_idstring | nulloptional
plan_statusPlanStatus | nulloptional: Der Status des Plans, als das Ereignis angenommen wurde. Nur generating verspricht, dass lesson_plan.ready oder lesson_plan.failed folgt. Jeder andere Wert ist ein Plan aus der Bibliothek, den Sie jetzt mit GET /v1/lesson-plans/{id} lesen können.
codestring | nulloptional
errorstring | nulloptional

Fehler

402application/json: Der Aufruf eines nutzungsbasiert abgerechneten Clients wurde abgelehnt, bevor er etwas verbraucht hat. spend_cap_reached: Der Client oder sein Konto hat sein monatliches Ausgabenlimit erreicht; erhöhe das Limit auf der Seite Integrationen. metered_billing_inactive: Die Nutzungsabrechnung ist für dieses Konto nicht aktiv; richte sie ein oder aktualisiere die Zahlungsmethode auf der Seite Integrationen.
410application/json: Die API-Version, unter der diese Anfrage beantwortet wird, wurde eingestellt. Sende eine unterstützte Version in Lingara-Version oder binde den Client an eine andere Version.
4XXapplication/json: Die Anfrage wurde abgelehnt. code nennt den Grund, und error beschreibt ihn in Worten.
503application/json · text/plain: Der Dienst ist vorübergehend nicht verfügbar; versuche es nach der in Retry-After angegebenen Anzahl Sekunden erneut. Während Wartungsarbeiten ist der Body reiner Text statt des Fehlerumschlags.
5XXapplication/json: Die Anfrage wurde abgelehnt. code nennt den Grund, und error beschreibt ihn in Worten.

codestringerforderlich: Warum die Anfrage abgelehnt wurde, als stabiler Code, nach dem du verzweigen kannst: zum Beispiel insufficient_scope (403), rate_limited (429) und, bei einem nutzungsbasiert abgerechneten Client, spend_cap_reached (402) und metered_billing_inactive (402).
errorstringerforderlich

Beispiel

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

Lieber eine Bibliothek? Siehe den Bereich Bibliotheken.