Envoyer un événement

Version de l'API 2026-10-affable-towhee

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

Indique à Lingara ce qui s'est passé dans votre jeu, par exemple l'arrivée de l'apprenant dans un nouveau lieu. L'événement est enregistré une seule fois et reçoit la réponse 202. Avec generate: true, Lingara démarre aussi un plan de leçon, qui nécessite lesson_plans:write et est limité et facturé comme POST /v1/lesson-plans : reaction nomme le plan, puis lesson_plan.ready ou lesson_plan.failed suit. Décrivez le monde, jamais le nom ou les messages d'un joueur.

Portées events:write

Paramètres

Lingara-Versionheaderstringfacultatif: La version de l'API sous laquelle traiter cette requête. Sans elle, un jeton d'accès obtient la version à laquelle son client est rattaché, et une requête sans jeton obtient la version actuelle. La version encore en développement ne s'atteint qu'en la nommant ici. Une version inconnue répond 400 avec le code api_version_unknown. GET /v1/versions liste les versions.
Idempotency-Keyheaderstringobligatoire: Une valeur que vous choisissez pour chaque événement et que vous renvoyez telle quelle lors d'une nouvelle tentative : de 1 à 255 caractères ASCII visibles, par exemple un UUID. Une nouvelle tentative avec la même clé reçoit la première réponse et n'est pas facturée à nouveau, même si son contenu diffère. Sans clé valide, la requête répond 400 avec le code idempotency_key_required.

Corps de la requête `application/json`

typestringobligatoire

dataWorldPracticeRequestedobligatoire

topicstringobligatoire
source_langstringobligatoire
target_langstringobligatoire
levelintegerobligatoire
tagsarray of stringfacultatif
generateboolean | nullfacultatif

Réponses

202 L'événement est enregistré

idstringobligatoire

typestringobligatoire

created_atstringobligatoire

reactionReactionReport | nullfacultatif

statusReactionStatusobligatoire
plan_idstring | nullfacultatif
plan_statusPlanStatus | nullfacultatif: Le statut du plan au moment où l'événement a été accepté. Seul generating promet que lesson_plan.ready ou lesson_plan.failed suivra. Toute autre valeur désigne un plan servi depuis la bibliothèque, que vous pouvez lire dès maintenant avec GET /v1/lesson-plans/{id}.
codestring | nullfacultatif
errorstring | nullfacultatif

Erreurs

402application/json: L'appel d'un client facturé à l'usage a été refusé avant qu'il ne dépense quoi que ce soit. spend_cap_reached : le client ou son compte a atteint sa limite de dépenses mensuelle ; relevez la limite sur la page Intégrations. metered_billing_inactive : la facturation à l'usage n'est pas active pour ce compte ; configurez-la ou mettez à jour le moyen de paiement sur la page Intégrations.
410application/json: La version de l'API sous laquelle cette requête est traitée a été retirée. Envoyez une version prise en charge dans Lingara-Version, ou rattachez le client à une autre version.
4XXapplication/json: La requête a été refusée. code indique pourquoi, et error l'explique en toutes lettres.
503application/json · text/plain: Le service est temporairement indisponible ; réessayez après le nombre de secondes indiqué dans Retry-After. Pendant la maintenance, le corps est du texte brut plutôt que l'enveloppe d'erreur.
5XXapplication/json: La requête a été refusée. code indique pourquoi, et error l'explique en toutes lettres.

codestringobligatoire: Pourquoi la requête a été refusée, sous forme de code stable sur lequel brancher votre logique : par exemple insufficient_scope (403), rate_limited (429) et, pour un client facturé à l'usage, spend_cap_reached (402) et metered_billing_inactive (402).
errorstringobligatoire

Exemple

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

Vous préférez une bibliothèque ? Consultez la section Bibliothèques.