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

{
  "request_id": "req_1001",
  "session_id": "ses_01J8Z",
  "client_reference": "crm-lead-8842",
  "status": "active",
  "turn_count": 0,
  "max_turns": 10,
  "turns_remaining": 10,
  "question_state": {
    "outcomes": []
  },
  "targets": {},
  "progress": {
    "objective": {
      "computed_status": "not_started",
      "progress": 0,
      "client_override": null,
      "effective_status": "not_started"
    },
    "sub_objectives": [
      {
        "id": "so_besoin",
        "order_position": 0,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      },
      {
        "id": "so_budget",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      },
      {
        "id": "so_livraison",
        "order_position": 2,
        "completion_role": "contributing",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      }
    ]
  },
  "pending_decision": null,
  "degraded": false,
  "versions": {
    "state_version": 0,
    "engine_version": "1.0.0",
    "api_version": "1.0"
  }
}

{
  "code": "unauthorized",
  "message": "Clé d'intégration absente ou invalide.",
  "request_id": "req_9000",
  "details": {}
}

{
  "code": "insufficient_scope",
  "message": "Cette clé ne permet pas de publier une configuration.",
  "request_id": "req_9001",
  "details": {
    "required_scopes": [
      "configuration:publish"
    ],
    "granted_scopes": [
      "configuration:read",
      "configuration:write"
    ]
  }
}

{
  "code": "idempotency_key_reused",
  "message": "Cette clé d'idempotence est déjà associée à une autre requête.",
  "request_id": "req_9002",
  "details": {
    "idempotency_key": "create-session-8842"
  }
}

{
  "code": "compiled_artifact_unavailable",
  "message": "L'artefact moteur de cette session est temporairement indisponible.",
  "request_id": "req_9010",
  "details": {
    "session_id": "ses_01J8Z"
  }
}

{
  "code": "invalid_choice",
  "message": "La valeur fournie n'est pas valide pour cette information de réussite.",
  "request_id": "req_9014",
  "details": {
    "data_id": "delivery_window",
    "invalid_value": "dans_deux_ans"
  }
}

{
  "code": "idempotency_contention",
  "message": "La clé d'idempotence n'a pas pu être réservée, réessayez.",
  "request_id": "req_9017",
  "details": {
    "idempotency_key": "next-ses01J8Z-turn-4",
    "retry_after_seconds": 1
  }
}

Sessions

Créer une session

Crée une session et l’épingle en interne sur la version de configuration publiée au moment de l’appel. La création ne renvoie pas encore de candidats : appeler POST /v1/sessions/{session_id}/next ensuite.

initial_history sert uniquement à reprendre une conversation commencée ailleurs — migration d’un intégrateur 0.9, ou échanges antérieurs à l’activation de NBQ. Il est consommé une seule fois en mémoire pour construire l’état initial, puis n’est persisté ni dans l’état, ni dans le journal, ni dans les logs applicatifs, et n’est jamais renvoyé. Si le tracing LLM est activé par Zelinqa, le prompt peut apparaître dans LangSmith EU selon la politique de diagnostic et de rétention V1.

POST

sessions

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

{
  "request_id": "req_1001",
  "session_id": "ses_01J8Z",
  "client_reference": "crm-lead-8842",
  "status": "active",
  "turn_count": 0,
  "max_turns": 10,
  "turns_remaining": 10,
  "question_state": {
    "outcomes": []
  },
  "targets": {},
  "progress": {
    "objective": {
      "computed_status": "not_started",
      "progress": 0,
      "client_override": null,
      "effective_status": "not_started"
    },
    "sub_objectives": [
      {
        "id": "so_besoin",
        "order_position": 0,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      },
      {
        "id": "so_budget",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      },
      {
        "id": "so_livraison",
        "order_position": 2,
        "completion_role": "contributing",
        "computed_status": "not_started",
        "progress": 0,
        "client_override": null,
        "effective_status": "not_started"
      }
    ]
  },
  "pending_decision": null,
  "degraded": false,
  "versions": {
    "state_version": 0,
    "engine_version": "1.0.0",
    "api_version": "1.0"
  }
}

{
  "code": "unauthorized",
  "message": "Clé d'intégration absente ou invalide.",
  "request_id": "req_9000",
  "details": {}
}

{
  "code": "insufficient_scope",
  "message": "Cette clé ne permet pas de publier une configuration.",
  "request_id": "req_9001",
  "details": {
    "required_scopes": [
      "configuration:publish"
    ],
    "granted_scopes": [
      "configuration:read",
      "configuration:write"
    ]
  }
}

{
  "code": "idempotency_key_reused",
  "message": "Cette clé d'idempotence est déjà associée à une autre requête.",
  "request_id": "req_9002",
  "details": {
    "idempotency_key": "create-session-8842"
  }
}

{
  "code": "compiled_artifact_unavailable",
  "message": "L'artefact moteur de cette session est temporairement indisponible.",
  "request_id": "req_9010",
  "details": {
    "session_id": "ses_01J8Z"
  }
}

{
  "code": "invalid_choice",
  "message": "La valeur fournie n'est pas valide pour cette information de réussite.",
  "request_id": "req_9014",
  "details": {
    "data_id": "delivery_window",
    "invalid_value": "dans_deux_ans"
  }
}

{
  "code": "idempotency_contention",
  "message": "La clé d'idempotence n'a pas pu être réservée, réessayez.",
  "request_id": "req_9017",
  "details": {
    "idempotency_key": "next-ses01J8Z-turn-4",
    "retry_after_seconds": 1
  }
}

Autorisations

Authorization

string

header

requis

Clé d'intégration préfixée nbq_live_, envoyée dans Authorization: Bearer nbq_live_… et résolue par l'authorizer Lambda de l'API Gateway publique. L'authorizer valide la clé, puis injecte en amont du service les headers de contexte x-tenant-id, x-nbq-id et x-scopes — x-scopes étant la liste des scopes de la clé séparés par des virgules, par exemple runtime,configuration:read.

Ces headers ne sont jamais acceptés depuis le client : toute valeur entrante est écrasée. Une clé absente ou invalide produit 401 au niveau de la passerelle ; une clé valide sans le scope requis produit 403 avec le code insufficient_scope.

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

Corps

application/json

Le client ne choisit ni la version de configuration, ni une politique d'accusé de réception : la session épingle en interne la version publiée active au moment de sa création.

client_reference

string

Référence opaque de l'intégrateur, renvoyée telle quelle pour corrélation.

Required string length: 1 - 128

max_turns

integer

Surcharge la limite souple définie dans la configuration. Atteindre cette limite ne coupe pas la conversation : /next continue de proposer la meilleure question avec un avertissement.

Plage requise: 1 <= x <= 100

initial_history

object[]

Historique de reprise, consommé une seule fois en mémoire pour construire l'état initial. Jamais persisté, jamais renvoyé.

Maximum array length: 100

Option 1
Option 2

Show child attributes

Réponse

Session créée.

request_id

string

requis

session_id

string

requis

client_reference

string | null

requis

status

enum<string>

requis

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

Compatibilité 0.9

Service

Créer une session

Autorisations

En-têtes

Corps

Réponse