> ## Documentation Index > Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Lire l'état public d'une session > Renvoie l'état de reprise complet : en-tête, résultats des questions, cibles touchées, progressions et contrôles client, décision en attente avec tous ses candidats réhydratés. Cette route rend inutile tout jeton de reprise côté client : après un crash, relire la session suffit pour retrouver `state_version` et les candidats exacts de la décision en attente. Ne renvoie jamais les embeddings, références de stockage internes, prompts, traces LLM ni preuves sémantiques détaillées. ## OpenAPI ````yaml /openapi.fr.yaml get /v1/sessions/{session_id} openapi: 3.1.0 info: title: NBQ Engine — API V1 version: 1.0.0 summary: Contrat public du runtime NBQ et de la configuration des bases de questions. description: > Contrat public de NBQ Engine V1, servi sur `https://api.zelinqa.ai`. Ce document est la **source de vérité** pour `nbq-sdk` (Python et TypeScript) et pour `nbq-mcp`. Les SDK et le serveur MCP sont générés ou alignés depuis ce contrat, jamais l'inverse. ## Pourquoi V1 succède à 0.9 La version publique déployée aujourd'hui est la bêta `0.9`, déjà servie sous le préfixe `/v1`. La V1 **ajoute** ses routes sous le même préfixe sans en modifier aucune : `POST /v1/next-questions` et `POST /v1/sessions/{session_id}/conversion` restent fonctionnelles et sont marquées dépréciées. La correspondance complète est décrite dans `docs/api-compat-0.9-to-v1.md`. ## Principes contractuels - **Le tenant n'est jamais fourni par le client.** L'authorizer de l'API Gateway publique résout la clé, puis injecte le tenant, le NBQ et les scopes. Tout header `x-tenant-id`, `x-nbq-id` ou `x-scopes` présent dans la requête entrante est écrasé. - **Toute mutation exige `Idempotency-Key`.** Même clé et même corps renvoient la réponse d'origine ; même clé et corps différent produisent `idempotency_key_reused`. - **Toute mutation d'une session existante exige `state_version`**, en contrôle optimiste. - **Les identifiants du tour précédent sont optionnels.** `decision_id`, `question_id` et `outcome` aident NBQ ; leur absence n'est pas une erreur, le moteur les résout depuis la décision en attente et les messages observés. Une valeur explicite du client reste prioritaire sur l'inférence. - **Le verbatim est optionnel.** `user_text` peut être omis quand une réponse structurée ou des mises à jour client suffisent : l'extraction sémantique est alors dégradée, signalée par `degraded_reasons`, mais le moteur reste fonctionnel. - **Aucun interne n'est exposé.** Ni score de sélection, ni preuve sémantique détaillée, ni embedding, ni prompt, ni prototype de réponse, ni matrice compilée n'apparaissent dans une réponse publique. - **Le client ne choisit pas la version de configuration.** La session épingle en interne la version publiée active au moment de sa création. ## Arrêts souples NBQ ne décide pas à la place de l'appelant. Lorsque `max_turns` est atteint, que l'objectif est déjà atteint ou que l'éligibilité normale est vide, `/next` renvoie **encore la meilleure question disponible** et signale la situation dans `warnings`. Un `action: stop` n'est produit que lorsqu'aucune question identifiable n'existe réellement. Les exclusions dures — question inactive, sous-objectif exclu par le client, contrainte stricte de l'appel — ne sont jamais violées, et toute question retournée porte un `question_id` valide. ## Scopes de clé API Une clé porte un ou plusieurs scopes. Studio recommande des clés séparées pour le runtime et pour la gestion, selon le principe du moindre privilège. | Scope | Autorise | |---|---| | `runtime` | les cinq routes de session | | `configuration:read` | `GET /v1/configuration` (publiée) et `GET /v1/configuration/questions` | | `configuration:write` | `POST /v1/configuration/changes` et la lecture du brouillon | Deux niveaux de contrôle se complètent. L'authorizer décide **statiquement**, à partir de la méthode et du chemin : c'est lui qui refuse une clé `runtime` sur `/v1/configuration/publish`. Le service ajoute un contrôle **dynamique** là où le scope dépend du contenu de la requête, que l'authorizer ne voit pas : aujourd'hui le seul cas est `?state=draft`, qui exige `configuration:write` sur une route dont l'authorizer n'exige que `configuration:read`. | `configuration:publish` | `POST /v1/configuration/publish` | Chaque opération déclare le scope exigé dans `x-required-scopes`. Un scope manquant produit `403 insufficient_scope`. ## Frontière de confiance L'API Configuration est implémentée par le service `bo-api` mais atteignable par deux portes qui n'ont pas la même confiance : - via l'**API Gateway publique** (`6nw77hkcib`, `api.zelinqa.ai`), l'authorizer Lambda authentifie la clé et **écrase** `x-tenant-id` et `x-scopes` ; ces headers font alors autorité ; - via l'**API Gateway bo-api** (`jdkpi8qlv5`, `bo-api.zelinqa.ai`), l'authentification vient des guards NestJS et du JWT Cognito ; **tous** les headers `x-tenant-id` et `x-scopes` fournis par l'appelant sont ignorés. Le service distingue obligatoirement l'origine via `requestContext.apiId` avant de construire son contexte d'autorisation. Un JWT valide sur la porte bo-api ne peut jamais obtenir un scope de publication en forgeant un header `x-*`. Ce document ne décrit que la surface publique `api.zelinqa.ai`. contact: name: Zelinqa url: https://docs.zelinqa.ai license: name: Proprietary — Zelinqa SAS identifier: LicenseRef-Zelinqa-Proprietary x-contract-status: frozen x-jira: NBQ-304 x-supersedes: openapi/nbq-runtime-v2.openapi.yaml x-compatibility-note: docs/api-compat-0.9-to-v1.md servers: - url: https://api.zelinqa.ai description: API publique NBQ security: - ApiKeyAuth: [] tags: - name: sessions description: | Cycle de vie d'une conversation NBQ : création, sélection de la question suivante, mises à jour hors tour, reprise et retour de résultat. - name: configuration description: | Lecture et modification de la configuration éditoriale d'un NBQ, puis publication asynchrone de l'artefact moteur. paths: /v1/sessions/{session_id}: get: tags: - sessions summary: Lire l'état public d'une session description: > Renvoie l'état de reprise complet : en-tête, résultats des questions, cibles touchées, progressions et contrôles client, décision en attente avec tous ses candidats réhydratés. Cette route rend inutile tout jeton de reprise côté client : après un crash, relire la session suffit pour retrouver `state_version` et les candidats exacts de la décision en attente. Ne renvoie jamais les embeddings, références de stockage internes, prompts, traces LLM ni preuves sémantiques détaillées. operationId: getSession parameters: - $ref: '#/components/parameters/SessionId' responses: '200': description: État public courant. content: application/json: schema: $ref: '#/components/schemas/SessionStateResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '404': $ref: '#/components/responses/UnknownSession' '410': $ref: '#/components/responses/CompiledArtifactUnavailable' components: parameters: SessionId: name: session_id in: path required: true schema: type: string minLength: 1 maxLength: 128 description: Identifiant opaque de session attribué par NBQ à la création. schemas: SessionStateResponse: type: object additionalProperties: false required: - request_id - session_id - client_reference - status - turn_count - max_turns - turns_remaining - question_state - targets - progress - pending_decision - degraded - versions properties: request_id: type: string session_id: type: string client_reference: type: - string - 'null' status: type: string enum: - active - completed - stopped turn_count: type: integer minimum: 0 max_turns: type: integer minimum: 1 turns_remaining: type: integer minimum: 0 question_state: $ref: '#/components/schemas/PublicQuestionState' targets: type: object additionalProperties: $ref: '#/components/schemas/PublicTargetState' description: > État sparse : seules les cibles réellement touchées sont présentes. Une cible absente est inconnue et sans couverture. progress: $ref: '#/components/schemas/ProgressView' pending_decision: oneOf: - $ref: '#/components/schemas/PendingDecisionView' - type: 'null' degraded: type: boolean versions: $ref: '#/components/schemas/VersionInfo' PublicQuestionState: type: object additionalProperties: false required: - outcomes description: > Aucun index `asked_ids`, `answered_ids` ou `refused_ids` n'est persisté ni exposé : ces ensembles se reconstruisent depuis `outcomes`. properties: outcomes: type: array items: $ref: '#/components/schemas/QuestionOutcomeRecord' PublicTargetState: type: object additionalProperties: false required: - kind - coverage description: > Vue publique d'une cible. Les preuves sémantiques détaillées, les deltas de couverture et les références d'embedding restent internes au moteur et ne sont jamais renvoyés. properties: kind: type: string enum: - data - exploration description: > `data` désigne une information de réussite : une donnée concrète dont la collecte permet de déclarer l'objectif atteint. `exploration` est la cible interne d'une question qui n'est reliée à aucune information de réussite. Elle mesure ce que la conversation a déjà couvert et évite les répétitions, mais ne bloque jamais la réussite de l'objectif. Les nouvelles publications sans prototypes évaluent directement les réponses réelles. Les sessions épinglées à un ancien artefact conservent leur méthode de couverture historique. status: type: string enum: - tentative - confirmed - conflicted - not_applicable description: > Présent uniquement pour `kind: data`. Une cible inconnue est absente de l'état plutôt que portée avec un statut `unknown`. `tentative` porte une valeur probable : elle fait monter `coverage` mais ne permet jamais de conclure ; `conflicted` signale plusieurs valeurs valides contradictoires ; `not_applicable` satisfait l'information sans valeur. value: description: >- Présente uniquement pour une information de réussite possédant une valeur courante. coverage: type: number minimum: 0 maximum: 1 description: > Ce que la conversation a déjà obtenu sur cette cible. Pour une information de réussite : `1` quand elle est `confirmed` ou `not_applicable`, `0` quand rien n'a été recueilli, et une valeur **intermédiaire** quand le statut est `tentative` — une valeur probable a été captée mais n'est pas encore assez fiable pour conclure. Une donnée `conflicted` retombe à `0` : des valeurs contradictoires n'apportent aucune certitude. Pour une cible d'exploration sans prototypes : meilleur soutien actif à la cible, dérivé des réponses réelles ; une réponse suffisante vaut `1`, sans devoir couvrir plusieurs exemples alternatifs. Une correction explicite peut réduire cette couverture. Pour les anciennes publications, le calcul historique sur les prototypes reste inchangé. ⚠️ `coverage` sert à mesurer l'avancement et à classer les questions, **jamais à décider de la réussite**. La complétion d'un sous-objectif se calcule à partir de `status`, où seuls `confirmed` et `not_applicable` comptent : une information `tentative` fait monter la progression visible sans jamais permettre de déclarer l'objectif atteint. Les deux grandeurs se ressemblent et ne se substituent pas l'une à l'autre. ProgressView: type: object additionalProperties: false required: - objective - sub_objectives properties: objective: $ref: '#/components/schemas/ObjectiveProgress' sub_objectives: type: array items: $ref: '#/components/schemas/SubObjectiveProgress' PendingDecisionView: type: object additionalProperties: false required: - decision_id - candidates description: > 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. properties: decision_id: type: string candidates: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/Candidate' VersionInfo: type: object additionalProperties: false required: - state_version - engine_version - api_version description: > 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. properties: state_version: type: integer minimum: 0 description: À renvoyer dans la mutation suivante de cette session. engine_version: type: string api_version: type: string const: '1.0' ErrorEnvelope: type: object additionalProperties: false required: - code - message - request_id - details description: Enveloppe uniforme de toutes les erreurs métier. properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string minLength: 1 request_id: type: string minLength: 1 details: type: object additionalProperties: true QuestionOutcomeRecord: type: object additionalProperties: false required: - question_id - decision_id - outcome - source properties: question_id: type: string decision_id: type: - string - 'null' description: Nul lorsque la question a été traitée hors d'une décision NBQ. outcome: $ref: '#/components/schemas/QuestionOutcome' source: type: string enum: - client - inferred description: Indique si l'outcome a été fourni par le client ou résolu par NBQ. message_id: type: - string - 'null' occurred_at: type: - string - 'null' format: date-time ObjectiveProgress: type: object additionalProperties: false required: - computed_status - progress - client_override - effective_status properties: computed_status: $ref: '#/components/schemas/ProgressStatus' progress: type: number minimum: 0 maximum: 1 description: > Agrégation des sous-objectifs pondérée par leur rôle de complétion. Les sous-objectifs exclus sortent du dénominateur. client_override: oneOf: - $ref: '#/components/schemas/ObjectiveClientOverrideView' - type: 'null' effective_status: $ref: '#/components/schemas/ProgressStatus' SubObjectiveProgress: type: object additionalProperties: false required: - id - order_position - completion_role - computed_status - progress - client_override - effective_status properties: id: type: string minLength: 1 maxLength: 128 order_position: type: integer minimum: 0 completion_role: $ref: '#/components/schemas/CompletionRole' computed_status: $ref: '#/components/schemas/ProgressStatus' progress: type: number minimum: 0 maximum: 1 client_override: oneOf: - $ref: '#/components/schemas/SubObjectiveClientOverrideView' - type: 'null' effective_status: type: string enum: - not_started - in_progress - covered - blocked - excluded description: > Statut consommable par le client après application de `client_override` au `computed_status` : sans override, le statut calculé ; `achieved` force `covered` ; `not_achieved` conserve le statut calculé sauf que `covered` redevient `in_progress` ; `excluded` retire le sous-objectif de la sélection et des agrégations de l'objectif. Candidate: type: object additionalProperties: false required: - rank - question_id - text - type - choices - target_ids description: | **Invariant garanti par le moteur**, couvert par les tests de contrat : `type: open` implique `choices` vide ; tout autre type implique au moins deux choix. properties: rank: type: integer minimum: 1 maximum: 10 question_id: type: string minLength: 1 maxLength: 128 description: >- Toujours un identifiant valide du corpus publié, y compris pour un repli. text: type: string minLength: 1 maxLength: 4000 description: > Libellé publié de la question. L'agent hôte reste libre de le reformuler : NBQ sait rattacher un texte reformulé à sa question au tour suivant. type: $ref: '#/components/schemas/QuestionType' choices: type: array maxItems: 50 items: $ref: '#/components/schemas/CandidateChoice' description: Vide pour une question ouverte. target_ids: type: array minItems: 1 uniqueItems: true items: type: string minLength: 1 maxLength: 128 description: Cibles que cette question adresse, principale en premier. ErrorCode: type: string description: Catalogue fermé des erreurs métier V1. enum: - unauthorized - insufficient_scope - idempotency_contention - state_version_conflict - idempotency_key_reused - unknown_session - invalid_previous_turn - constraint_no_match - invalid_choice - compiled_artifact_unavailable - configuration_validation_failed - compilation_in_progress - unknown_configuration - unknown_compilation QuestionOutcome: type: string enum: - asked_answered - asked_no_answer - refused description: > Résultat d'une question effectivement posée. - `asked_answered` : question posée et réponse exploitable reçue ; - `asked_no_answer` : question posée, aucune réponse exploitable ; - `refused` : refus explicite de répondre. Une question jamais posée n'a pas de résultat : elle est simplement absente. Il n'existe pas de valeur `skipped` — une proposition que l'agent n'a pas utilisée est journalisée comme décision ignorée, jamais comme un faux résultat sur la question. ProgressStatus: type: string enum: - not_started - in_progress - covered - blocked ObjectiveClientOverrideView: type: object additionalProperties: false required: - status properties: status: $ref: '#/components/schemas/ObjectiveOverrideValue' updated_at: type: string format: date-time CompletionRole: type: string enum: - blocking - contributing - optional description: > Rôle d'un sous-objectif dans la réussite de l'objectif. - `blocking` : doit être couvert pour conclure normalement ; - `contributing` : participe au niveau de qualification exigé ; - `optional` : améliore la conversation mais ne bloque jamais la réussite. Le poids moteur est dérivé du rôle. Le client ne saisit aucun poids métier. SubObjectiveClientOverrideView: type: object additionalProperties: false required: - status properties: status: $ref: '#/components/schemas/SubObjectiveOverrideValue' updated_at: type: string format: date-time QuestionType: type: string enum: - open - single_choice - multiple_choice - semi_open description: | - `open` : réponse libre, aucun choix ; - `single_choice` : un seul choix parmi la liste ; - `multiple_choice` : plusieurs choix possibles ; - `semi_open` : choix proposés, complément libre autorisé via `structured_answer.free_text`. Le mode de sélection est porté par le type lui-même : aucun champ `selection_mode` séparé n'existe en V1. CandidateChoice: type: object additionalProperties: false required: - choice_id - label properties: choice_id: type: string minLength: 1 maxLength: 128 label: type: string minLength: 1 maxLength: 500 ObjectiveOverrideValue: type: string enum: - achieved - not_achieved SubObjectiveOverrideValue: type: string enum: - achieved - not_achieved - excluded description: > `achieved` force le sous-objectif à couvert. `not_achieved` empêche une complétion calculée prématurée. `excluded` le retire de la sélection et des dénominateurs de progression de l'objectif. responses: Unauthorized: description: > Clé absente, malformée, inconnue, révoquée, expirée, ou rattachée à un NBQ suspendu. Le refus vient de l'authorizer de la passerelle, avant que la requête n'atteigne le service : le corps est donc produit par la passerelle et peut ne pas suivre l'enveloppe d'erreur métier. La distinction avec `403` est nette : `401` signifie « je ne sais pas qui vous êtes », `403` signifie « je sais qui vous êtes, mais cette clé ne porte pas le scope requis ». content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: unauthorized message: Clé d'intégration absente ou invalide. request_id: req_9000 details: {} InsufficientScope: description: > La clé est valide mais ne porte pas le scope exigé par l'opération. Une clé absente ou invalide produit `401` au niveau de la passerelle, avant d'atteindre le service. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: 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 UnknownSession: description: Session inconnue, ou appartenant à un autre tenant. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: unknown_session message: La session demandée est inconnue. request_id: req_9007 details: session_id: ses_inconnue CompiledArtifactUnavailable: description: > L'artefact compilé épinglé par la session est réellement inaccessible. Une configuration simplement remplacée par une version plus récente ne produit pas cette erreur : l'ancienne version reste lisible pour terminer les sessions qui l'utilisent déjà. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: compiled_artifact_unavailable message: >- L'artefact moteur de cette session est temporairement indisponible. request_id: req_9010 details: session_id: ses_01J8Z securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: NBQ API key description: > 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`. ````