> ## 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.

# Sonde de disponibilité

> Route publique sans authentification, conservée depuis la bêta 0.9. Ne
renvoie aucune donnée de tenant.




## OpenAPI

````yaml /openapi.fr.yaml get /v1/health
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/health:
    get:
      tags:
        - legacy
      summary: Sonde de disponibilité
      description: |
        Route publique sans authentification, conservée depuis la bêta 0.9. Ne
        renvoie aucune donnée de tenant.
      operationId: health
      responses:
        '200':
          description: Service disponible.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
              example:
                status: ok
                nbq_version: 1.0.0
      security: []
components:
  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`.

````