curl --request POST \
  --url https://api.zelinqa.ai/v1/sessions/{session_id}/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "state_version": 2,
  "client_updates": {
    "data": [
      {
        "id": "company_size",
        "value": 120
      }
    ]
  }
}
'

{
  "request_id": "<string>",
  "session_id": "<string>",
  "client_reference": "<string>",
  "status": "active",
  "turn_count": 1,
  "max_turns": 2,
  "turns_remaining": 1,
  "question_state": {
    "outcomes": [
      {
        "question_id": "<string>",
        "decision_id": "<string>",
        "outcome": "asked_answered",
        "source": "client",
        "message_id": "<string>",
        "occurred_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "targets": {},
  "progress": {
    "objective": {
      "computed_status": "not_started",
      "progress": 0.5,
      "client_override": {
        "status": "achieved",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "effective_status": "not_started"
    },
    "dimensions": [
      {
        "id": "<string>",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0.5,
        "client_override": {
          "status": "achieved",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "effective_status": "not_started"
      }
    ]
  },
  "pending_decision": {
    "decision_id": "<string>",
    "candidates": [
      {
        "rank": 5,
        "question_id": "<string>",
        "text": "<string>",
        "type": "open",
        "choices": [
          {
            "choice_id": "<string>",
            "label": "<string>"
          }
        ],
        "target_ids": [
          "<string>"
        ],
        "selection_mode": "single"
      }
    ]
  },
  "degraded": true,
  "versions": {
    "state_version": 1,
    "engine_version": "<string>",
    "api_version": "1.0"
  }
}

Sessions

Appliquer un contexte ou une mise à jour sans consommer de tour

Même réducteur que /next, sans consommer de tour. Sert à rattraper des messages qui n’ont pas transité par Zelinqa, synchroniser une donnée déjà connue du système appelant, corriger une valeur, ou piloter une dimension.

Le contexte fourni peut résoudre la décision en attente lorsqu’il y répond sans ambiguïté ; pending_decision vaut alors null et le prochain /next propose la suite. Sinon, la décision en attente est recalculée sur l’état mis à jour, avec les contraintes selection du /next qui l’a proposée, sans appel à un modèle :

même liste de candidates : la décision et son decision_id sont conservés ;
liste différente : pending_decision porte une nouvelle décision, avec un nouveau decision_id. C’est elle que l’agent hôte doit poser. Par exemple, une donnée confirmée par client_updates pour la question en attente retire cette question ;
plus aucune question disponible : la session s’arrête (status: stopped), comme un /next qui répondrait stop_reason: no_question_available. Si seules les contraintes selection d’origine ne laissent plus de question, pending_decision vaut null, la session reste active et le prochain /next choisit avec ses propres contraintes.

Lorsque la limite max_turns est atteinte, la session s’arrête et pending_decision vaut null.

Une réponse à une décision ainsi remplacée reste acceptée par /next : voir previous_turn.decision_id.

POST

sessions

{session_id}

events

curl --request POST \
  --url https://api.zelinqa.ai/v1/sessions/{session_id}/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "state_version": 2,
  "client_updates": {
    "data": [
      {
        "id": "company_size",
        "value": 120
      }
    ]
  }
}
'

{
  "request_id": "<string>",
  "session_id": "<string>",
  "client_reference": "<string>",
  "status": "active",
  "turn_count": 1,
  "max_turns": 2,
  "turns_remaining": 1,
  "question_state": {
    "outcomes": [
      {
        "question_id": "<string>",
        "decision_id": "<string>",
        "outcome": "asked_answered",
        "source": "client",
        "message_id": "<string>",
        "occurred_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "targets": {},
  "progress": {
    "objective": {
      "computed_status": "not_started",
      "progress": 0.5,
      "client_override": {
        "status": "achieved",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "effective_status": "not_started"
    },
    "dimensions": [
      {
        "id": "<string>",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0.5,
        "client_override": {
          "status": "achieved",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "effective_status": "not_started"
      }
    ]
  },
  "pending_decision": {
    "decision_id": "<string>",
    "candidates": [
      {
        "rank": 5,
        "question_id": "<string>",
        "text": "<string>",
        "type": "open",
        "choices": [
          {
            "choice_id": "<string>",
            "label": "<string>"
          }
        ],
        "target_ids": [
          "<string>"
        ],
        "selection_mode": "single"
      }
    ]
  },
  "degraded": true,
  "versions": {
    "state_version": 1,
    "engine_version": "<string>",
    "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

Option 1
Option 2

state_version

integer

requis

Plage requise: x >= 0

context_update

object

requis

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

Réponse

État public après application des mises à jour, avec la décision en attente conservée, remplacée ou retirée.

request_id

string

requis

session_id

string

requis

client_reference

string | null

requis

status

enum<string>

requis

stopped : la conversation est terminée. Un appel /next a renvoyé action: stop, ou /events a atteint max_turns ou n'a laissé aucune question disponible. Une session arrêtée par max_turns_reached ne propose plus de question.

Options disponibles:

active,

completed,

stopped

turn_count

integer

requis

Plage requise: x >= 0

max_turns

integer

requis

Plage requise: x >= 1

turns_remaining

integer

requis

Plage requise: x >= 0

question_state

object

requis

Aucun index asked_ids, answered_ids ou refused_ids n'est persisté ni exposé : ces ensembles se reconstruisent depuis outcomes.

Show child attributes

targets

object

requis

État sparse : seules les cibles réellement touchées sont présentes. Une cible absente est inconnue et sans couverture.

Show child attributes

progress

object

requis

Show child attributes

pending_decision

object | null

requis

Décision proposée et pas encore résolue. Les candidats sont réhydratés depuis la configuration épinglée : après un crash, relire la session suffit pour reprendre exactement où l'on s'était arrêté. Aucun jeton de reprise n'existe.

Show child attributes

degraded

boolean

requis

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

Appliquer un contexte ou une mise à jour sans consommer de tour

Autorisations

En-têtes

Paramètres de chemin

Corps

Réponse