curl --request POST \
  --url https://api.zelinqa.ai/v1/sessions/{session_id}/next \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "state_version": 0
}
'

{
  "request_id": "req_1002",
  "session_id": "ses_01J8Z",
  "decision_id": "dec_7f2a",
  "action": "ask",
  "stop_reason": null,
  "candidates": [
    {
      "rank": 1,
      "question_id": "q_budget",
      "text": "Quel budget souhaitez-vous consacrer au canapé ?",
      "type": "open",
      "choices": [],
      "target_ids": [
        "annual_budget"
      ]
    },
    {
      "rank": 2,
      "question_id": "q_delai",
      "text": "À quelle période souhaitez-vous être livré ?",
      "type": "single_choice",
      "choices": [
        {
          "choice_id": "choice_1m",
          "label": "Dans le mois"
        },
        {
          "choice_id": "choice_3m",
          "label": "Dans les trois mois"
        },
        {
          "choice_id": "choice_later",
          "label": "Plus tard"
        }
      ],
      "target_ids": [
        "delivery_window"
      ]
    }
  ],
  "progress": {
    "objective": {
      "computed_status": "in_progress",
      "progress": 0.34,
      "client_override": null,
      "effective_status": "in_progress"
    },
    "dimensions": [
      {
        "id": "so_besoin",
        "order_position": 0,
        "completion_role": "blocking",
        "computed_status": "covered",
        "progress": 1,
        "client_override": null,
        "effective_status": "covered"
      },
      {
        "id": "so_budget",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "in_progress",
        "progress": 0.15,
        "client_override": null,
        "effective_status": "in_progress"
      },
      {
        "id": "so_livraison",
        "order_position": 2,
        "completion_role": "contributing",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      }
    ]
  },
  "turn_count": 2,
  "turns_remaining": 8,
  "warnings": [],
  "degraded": false,
  "degraded_reasons": [],
  "versions": {
    "state_version": 4,
    "engine_version": "1.0.0",
    "api_version": "1.0"
  }
}

Sessions

Comprendre le tour précédent et proposer les questions suivantes

Route principale du runtime. En un seul appel, le moteur résout la question réellement posée et son outcome, applique les mises à jour du client, réduit l’état, recalcule les progressions, puis classe les questions éligibles.

Le client n’a pas à savoir quelle candidate son agent a utilisée : si decision_id, question_id ou outcome sont absents, Zelinqa les résout depuis la décision en attente, le texte de l’agent, la réponse structurée et le contexte. Une reformulation de la question par l’agent hôte reste rattachable.

Au premier appel d’une session neuve, previous_turn est absent.

Lorsque previous_turn répond à la dernière question autorisée par max_turns, ce tour est enregistré puis la réponse est action: stop avec stop_reason: max_turns_reached. Les appels suivants renvoient le même arrêt.

/events peut remplacer la décision en attente après que l’agent hôte a déjà posé sa question. Une réponse dont previous_turn.decision_id désigne la dernière décision remplacée est donc acceptée jusqu’au prochain /next abouti :

si previous_turn.question_id figure encore parmi les candidates de la décision courante, la réponse lui est rattachée normalement ;
sinon, previous_turn est lu comme un contexte en mode messages : les données qu’il contient sont extraites, aucun outcome n’est enregistré pour la question retirée et aucun tour n’est consommé. La réponse renvoie la décision courante, avec le même decision_id, si la sélection la redonne à l’identique, et sinon une nouvelle décision.

Un decision_id qui ne désigne ni la décision en attente ni la dernière décision remplacée reste refusé en invalid_previous_turn.

POST

sessions

{session_id}

curl --request POST \
  --url https://api.zelinqa.ai/v1/sessions/{session_id}/next \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "state_version": 0
}
'

{
  "request_id": "req_1002",
  "session_id": "ses_01J8Z",
  "decision_id": "dec_7f2a",
  "action": "ask",
  "stop_reason": null,
  "candidates": [
    {
      "rank": 1,
      "question_id": "q_budget",
      "text": "Quel budget souhaitez-vous consacrer au canapé ?",
      "type": "open",
      "choices": [],
      "target_ids": [
        "annual_budget"
      ]
    },
    {
      "rank": 2,
      "question_id": "q_delai",
      "text": "À quelle période souhaitez-vous être livré ?",
      "type": "single_choice",
      "choices": [
        {
          "choice_id": "choice_1m",
          "label": "Dans le mois"
        },
        {
          "choice_id": "choice_3m",
          "label": "Dans les trois mois"
        },
        {
          "choice_id": "choice_later",
          "label": "Plus tard"
        }
      ],
      "target_ids": [
        "delivery_window"
      ]
    }
  ],
  "progress": {
    "objective": {
      "computed_status": "in_progress",
      "progress": 0.34,
      "client_override": null,
      "effective_status": "in_progress"
    },
    "dimensions": [
      {
        "id": "so_besoin",
        "order_position": 0,
        "completion_role": "blocking",
        "computed_status": "covered",
        "progress": 1,
        "client_override": null,
        "effective_status": "covered"
      },
      {
        "id": "so_budget",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "in_progress",
        "progress": 0.15,
        "client_override": null,
        "effective_status": "in_progress"
      },
      {
        "id": "so_livraison",
        "order_position": 2,
        "completion_role": "contributing",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      }
    ]
  },
  "turn_count": 2,
  "turns_remaining": 8,
  "warnings": [],
  "degraded": false,
  "degraded_reasons": [],
  "versions": {
    "state_version": 4,
    "engine_version": "1.0.0",
    "api_version": "1.0"
  }
}

Autorisations

Authorization

string

header

requis

Envoyez la clé API dans Authorization: Bearer <clé>. Elle identifie le domaine et les droits autorisés. Ne transmettez pas d'en-têtes d'identité internes.

En-têtes

Idempotency-Key

string

requis

Clé unique par mutation logique, choisie par l'appelant.

Même clé et même corps renvoient exactement la réponse d'origine, sans rejouer l'effet : aucun retry ne double turn_count, un outcome, un événement, un feedback ou une publication. Même clé avec un corps différent produit 409 idempotency_key_reused.

Les enregistrements sont isolés par tenant et par opération, et sont purgés après 24 heures. Passé ce délai, la même clé est traitée comme neuve.

Required string length: 8 - 128

Paramètres de chemin

session_id

string

requis

Identifiant opaque de session attribué par Zelinqa à la création.

Required string length: 1 - 128

Corps

application/json

state_version

integer

requis

Version lue par le client avant cette mutation, en contrôle optimiste.

Plage requise: x >= 0

previous_turn

object

Observation du dernier échange ; absente au premier appel d'une session neuve. Les identifiants de décision et de question sont facultatifs et ne doivent pas être inventés. Pour une question ouverte répondue, user_text non vide est obligatoire, sauf si outcome vaut explicitement asked_no_answer ou refused. Sinon, l'API renvoie 422 invalid_previous_turn avant toute analyse par modèle. Les questions fermées et semi-ouvertes acceptent des choice_ids seuls ; une semi-ouverte peut aussi porter free_text. Ni context_update ni client_updates ne remplacent le texte requis.

Show child attributes

context_update

object

Contexte apparu depuis le dernier appel Zelinqa. Le client choisit un résumé compact ou le delta ordonné des messages ; il ne renvoie jamais l'historique déjà traité.

Option 1
Option 2

Show child attributes

client_updates

object

Mises à jour explicites du système appelant, prioritaires sur l'inférence.

Show child attributes

selection

object

Contraintes valables pour cet appel uniquement. Elles sont appliquées avant le calcul du classement, jamais en filtrant un top 3 déjà constitué.

Show child attributes

Réponse

Décision calculée, ou arrêt explicite lorsque la limite de tours est atteinte ou qu'aucune question n'existe.

Aucun score de sélection n'est exposé : le classement est porté par rank. Un score brut n'a pas de sens métier hors du moteur et ne doit pas devenir une dépendance des intégrations.

Invariants garantis par le moteur, non exprimés en JSON Schema pour rester générables en SDK :

action: ask implique decision_id non nul, stop_reason nul et au moins un candidat ;
action: stop implique decision_id nul, stop_reason renseigné et candidates vide.

request_id

string

requis

session_id

string

requis

decision_id

string | null

requis

Non nul quand action vaut ask. À renvoyer dans le tour suivant si disponible.

action

enum<string>

requis

stop est produit dans deux cas, précisés par stop_reason : la limite max_turns est atteinte, ou aucune question identifiable n'existe. Un objectif déjà atteint ou une éligibilité normale vide ne coupent pas la conversation : le moteur propose encore la meilleure question disponible et le signale dans warnings. Avant la limite de tours, la décision d'arrêter appartient à l'appelant.

Options disponibles:

ask,

stop

stop_reason

enum<string> | null

requis

Cause de l'arrêt :

max_turns_reached : la session a atteint max_turns. Le dernier tour autorisé est enregistré ; les appels /next suivants renvoient le même arrêt sans analyser le tour ni modifier la session ;
no_question_available : aucune question identifiable ne subsiste après application des exclusions dures — question inactive, dimension exclu par le client, contrainte stricte de l'appel.

Les autres situations terminales remontent par warnings, la conversation restant décidée par l'appelant.

Options disponibles:

no_question_available,

max_turns_reached

candidates

object[]

requis

Ordonnées par pertinence décroissante, rang 1 en premier. Lorsque plusieurs candidats sont demandés, le moteur simule la couverture apportée par le premier avant de choisir le suivant : deux variantes demandant la même information ne sont pas retournées ensemble.

Maximum array length: 10

Show child attributes

progress

object

requis

Show child attributes

turn_count

integer

requis

Plage requise: x >= 0

turns_remaining

integer

requis

Vaut 0 lorsque la limite de tours est atteinte ; action vaut alors stop.

Plage requise: x >= 0

warnings

enum<string>[]

requis

Conditions d'arrêt réunies, sans que Zelinqa interrompe la conversation.

objective_achieved : les conditions de réussite sont satisfaites ;
eligibility_exhausted_fallback : plus aucune question n'était éligible normalement, la proposition est un repli — elle porte tout de même un question_id valide et respecte les exclusions dures ;
constraints_relaxed : une préférence prefer a dû être élargie.

Options disponibles:

objective_achieved,

eligibility_exhausted_fallback,

constraints_relaxed

degraded

boolean

requis

Vrai lorsque la compréhension du tour a été effectuée en mode réduit.

degraded_reasons

enum<string>[]

requis

Options disponibles:

missing_user_text,

summary_only_context,

semantic_service_unavailable,

unresolved_previous_turn

versions

object

requis

La version de configuration épinglée par la session n'est pas exposée : le client ne la choisit pas et ne doit pas s'y adosser.

Show child attributes

Guides API

Sessions

Configuration

Service

Comprendre le tour précédent et proposer les questions suivantes

Autorisations

En-têtes

Paramètres de chemin

Corps

Réponse