> ## 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 la configuration éditoriale > Renvoie les quatre objets configurés dans NBQ Studio : objectif, sous-objectifs, informations de réussite et questions. `state=published` (défaut) renvoie la configuration active et exige `configuration:read`. `state=draft` renvoie le brouillon en cours d'édition et exige `configuration:write`. Cette route n'expose jamais les internes de compilation : ni prototypes de réponse, ni graphe `R`, ni matrices `R_k` ou `G`, ni artefact. ## OpenAPI ````yaml /openapi.fr.yaml get /v1/configuration 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/configuration: get: tags: - configuration summary: Lire la configuration éditoriale description: > Renvoie les quatre objets configurés dans NBQ Studio : objectif, sous-objectifs, informations de réussite et questions. `state=published` (défaut) renvoie la configuration active et exige `configuration:read`. `state=draft` renvoie le brouillon en cours d'édition et exige `configuration:write`. Cette route n'expose jamais les internes de compilation : ni prototypes de réponse, ni graphe `R`, ni matrices `R_k` ou `G`, ni artefact. operationId: getConfiguration parameters: - name: state in: query required: false schema: type: string enum: - published - draft default: published description: > `published` exige `configuration:read`. `draft` exige `configuration:write` : lire un brouillon revient à voir du travail non publié, ce qui relève de l'édition plutôt que de la consultation. **Ce contrôle est dynamique, appliqué par le service, pas par l'authorizer.** L'authorizer de la passerelle décide à partir de la méthode et du chemin ; il ne voit pas les paramètres de requête et ne peut donc pas distinguer `?state=draft` de `?state=published`. Il n'exige ici que `configuration:read`, et le service refuse ensuite avec `403 insufficient_scope` si `state=draft` est demandé sans `configuration:write`. responses: '200': description: Configuration demandée. content: application/json: schema: $ref: '#/components/schemas/ConfigurationResponse' examples: publiee: $ref: '#/components/examples/ConfigurationPubliee' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '404': $ref: '#/components/responses/UnknownConfiguration' components: schemas: ConfigurationResponse: type: object additionalProperties: false required: - request_id - state - objective - sub_objectives - success_informations - questions description: > Les quatre objets visibles dans NBQ Studio. Ni prototypes de réponse, ni graphe de relations, ni matrices, ni artefact compilé n'apparaissent ici : ce sont des internes de compilation. properties: request_id: type: string state: type: string enum: - published - draft configuration_version: type: - string - 'null' description: Renseignée pour `published`, nulle pour un brouillon jamais publié. draft_revision: type: - integer - 'null' description: >- Renseignée pour `draft`, à passer en `expected_draft_revision` lors de la publication. published_at: type: - string - 'null' format: date-time objective: $ref: '#/components/schemas/Objective' sub_objectives: type: array items: $ref: '#/components/schemas/SubObjective' success_informations: type: array items: $ref: '#/components/schemas/SuccessInformation' questions: type: array items: $ref: '#/components/schemas/ConfiguredQuestion' Objective: type: object additionalProperties: false required: - name - qualification_level - max_turns - candidates_per_call - order_strength description: > Champs volontairement absents en V1 : `min_turns_before_auto_complete`, `retention_mode`, `business_weight`, et toute version de corpus choisie par le client. properties: name: type: string minLength: 1 maxLength: 200 description: type: string maxLength: 4000 qualification_level: $ref: '#/components/schemas/QualificationLevel' max_turns: type: integer minimum: 1 maximum: 100 description: Limite souple. L'atteindre ne coupe pas la conversation. candidates_per_call: type: integer minimum: 1 maximum: 10 order_strength: type: number minimum: 0 maximum: 1 description: >- Force avec laquelle l'ordre des sous-objectifs influence la sélection. SubObjective: type: object additionalProperties: false required: - id - name - order_position - completion_role properties: id: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 200 order_position: type: integer minimum: 0 completion_role: $ref: '#/components/schemas/CompletionRole' SuccessInformation: type: object additionalProperties: false required: - id - label - schema - primary_question_id description: > Une information de réussite est obligatoire par définition : aucun champ `required` n'est exposé. Son rattachement à un sous-objectif est dérivé de sa question principale, et elle ne peut pas dépendre uniquement d'un sous-objectif `optional`. properties: id: type: string minLength: 1 maxLength: 128 label: type: string minLength: 1 maxLength: 200 schema: type: object additionalProperties: true description: Schéma JSON de validation de la valeur collectée. primary_question_id: type: string minLength: 1 maxLength: 128 description: >- Question active désignée comme principale pour collecter cette information. ConfiguredQuestion: type: object additionalProperties: false required: - id - text - type - sub_objective_id - active - choices description: > Champs volontairement absents en V1 : `must_ask`, `requirement_policy`, `importance`, `editor_weight`, `cost_profile`, sensibilité, effort et `expected_answer_elements`. Une question devient nécessaire parce qu'elle est la meilleure manière encore disponible d'obtenir une information manquante, pas parce qu'un éditeur l'a marquée obligatoire. properties: id: type: string minLength: 1 maxLength: 128 text: type: string minLength: 1 maxLength: 4000 type: $ref: '#/components/schemas/QuestionType' choices: type: array maxItems: 50 items: $ref: '#/components/schemas/ConfiguredChoice' sub_objective_id: type: string minLength: 1 maxLength: 128 description: Exactement un sous-objectif. active: type: boolean 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 QualificationLevel: type: string enum: - essential - balanced - deep description: > Exigence de couverture des sous-objectifs `contributing`. - `essential` : seules les informations de réussite et les sous-objectifs `blocking` sont exigés ; - `balanced` : couverture moyenne des `contributing` exigée à `0.80` ; - `deep` : couverture moyenne des `contributing` exigée à `1.00`. 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. 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. ConfiguredChoice: type: object additionalProperties: false required: - id - label properties: id: type: string minLength: 1 maxLength: 128 label: type: string minLength: 1 maxLength: 500 maps_to_value: description: | Valeur produite pour l'information de réussite lorsque ce choix est sélectionné. Permet le mapping déterministe sans appel LLM. 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 examples: ConfigurationPubliee: summary: Configuration active d'un NBQ de qualification mobilier value: request_id: req_1005 state: published configuration_version: cfg_00013 draft_revision: null published_at: '2026-08-28T14:02:00Z' objective: name: Qualifier un projet de canapé description: >- Comprendre le besoin, le budget et le délai avant de recommander un produit. qualification_level: balanced max_turns: 10 candidates_per_call: 3 order_strength: 0.35 sub_objectives: - id: so_besoin name: Besoin et usage order_position: 0 completion_role: blocking - id: so_budget name: Budget order_position: 1 completion_role: blocking - id: so_livraison name: Délai de livraison order_position: 2 completion_role: contributing success_informations: - id: annual_budget label: Budget envisagé primary_question_id: q_budget schema: type: number minimum: 0 - id: delivery_window label: Fenêtre de livraison souhaitée primary_question_id: q_delai schema: type: string enum: - dans_le_mois - trois_mois - plus_tard questions: - id: q_style text: Quel style de canapé recherchez-vous ? type: single_choice sub_objective_id: so_besoin active: true choices: - id: choice_contemporain label: Contemporain - id: choice_scandinave label: Scandinave - id: choice_classique label: Classique - id: q_budget text: Quel budget souhaitez-vous consacrer au canapé ? type: open sub_objective_id: so_budget active: true choices: [] - id: q_delai text: À quelle période souhaitez-vous être livré ? type: single_choice sub_objective_id: so_livraison active: true choices: - id: choice_1m label: Dans le mois maps_to_value: dans_le_mois - id: choice_3m label: Dans les trois mois maps_to_value: trois_mois - id: choice_later label: Plus tard maps_to_value: plus_tard 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 UnknownConfiguration: description: > Aucune configuration ne correspond à l'état demandé — par exemple un brouillon qui n'a jamais été créé. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: unknown_configuration message: Aucun brouillon n'existe pour cette configuration. request_id: req_9008 details: state: draft 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`. ````