Skip to main content
L’API REST permet d’intégrer Zelinqa directement depuis votre backend. Les SDK et le serveur MCP utilisent aussi cette API. Votre backend conserve les identifiants retournés par Zelinqa et appelle le moteur lorsque votre expérience a besoin d’une nouvelle question.

​
Responsabilités

​
Boucle recommandée

  1. Créez une session une fois avec POST /v1/sessions.
  2. Appelez /next avec la dernière state_version.
  3. Utilisez candidates[0], ou choisissez parmi les candidats si votre produit le nécessite.
  4. Après la réponse, appelez de nouveau /next avec previous_turn.
  5. Envoyez les informations externes par /events sans provoquer une nouvelle sélection.
  6. Envoyez le résultat final par /feedback.
Si votre backend redémarre, relisez la session avec GET /v1/sessions/{session_id}. Ne reconstruisez pas l’état à partir d’une copie locale obsolète.

​
Réponses à choix

Lorsque votre interface affiche les choix fournis par Zelinqa, renvoyez leurs choice_id dans structured_answer.choice_ids. Cela évite une interprétation sémantique inutile et conserve un mapping déterministe.

​
Privilégier les réponses structurées

Si votre application connaît déjà le sens de la réponse, transmettez-le directement :
  • previous_turn.outcome indique si la question a reçu une réponse exploitable, aucune réponse ou un refus ;
  • structured_answer.choice_ids transmet les choix d’une question fermée ou semi-ouverte ;
  • client_updates.data envoie une donnée métier déjà validée par votre système.
La donnée déjà confirmée dans client_updates est appliquée de façon structurée. Ici, la question est ouverte : même avec une donnée confirmée, la réponse réellement donnée dans user_text reste obligatoire et peut être analysée par le moteur. Pour une question fermée ou semi-ouverte, des choice_ids seuls suffisent si la personne n’a rien ajouté ; ce chemin peut éviter l’analyse par modèle. N’inventez jamais une valeur incertaine.
outcome décrit le résultat de la question, mais ne remplace pas user_text pour une question ouverte répondue et ne crée pas à lui seul une donnée métier. Utilisez également structured_answer ou client_updates lorsque votre système connaît l’information obtenue.

Appels HTTP avec curl

Exécutez le cycle minimal avant de l’intégrer dans votre application.