> ## 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 Zelinqa Studio : objectif,
dimensions, 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: Zelinqa — API V1
  version: 1.0.0
  summary: >-
    Contrat public du runtime Zelinqa et de la configuration des bases de
    questions.
  description: >-
    Contrat public de l'API Zelinqa V1 sur https://api.zelinqa.ai. La clé API
    identifie le domaine et ses droits. Les mutations utilisent Idempotency-Key
    ; celles d'une session existante utilisent aussi state_version. Les sessions
    restent attachées à leur version publiée.
  contact:
    name: Zelinqa
    url: https://docs.zelinqa.ai
  license:
    name: Proprietary — Zelinqa SAS
    identifier: LicenseRef-Zelinqa-Proprietary
servers:
  - url: https://api.zelinqa.ai
    description: API publique Zelinqa
security:
  - ApiKeyAuth: []
tags:
  - name: sessions
    description: >
      Cycle de vie d'une conversation Zelinqa : 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 domaine, 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 Zelinqa Studio : objectif,

        dimensions, 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.


            La lecture du brouillon exige aussi `configuration:read`. Une clé

            dépourvue de `configuration:write` reçoit `403 insufficient_scope`.
      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
        - domain
        - objective
        - dimensions
        - success_informations
        - questions
      description: >
        Le domaine courant et les quatre objets configurés dans Zelinqa 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
        domain:
          $ref: '#/components/schemas/DomainMetadata'
        objective:
          $ref: '#/components/schemas/Objective'
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/Dimension'
        success_informations:
          type: array
          items:
            $ref: '#/components/schemas/SuccessInformation'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/ConfiguredQuestion'
    DomainMetadata:
      type: object
      additionalProperties: false
      required:
        - name
      description: >-
        Nom actuel du domaine, relu sans republication. Distinct de l'objectif
        versionné.
      properties:
        name:
          type: string
    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 dimensions influence la sélection.
    Dimension:
      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 à une dimension est dérivé de
        sa

        question principale, et elle ne peut pas dépendre uniquement d'un

        dimension `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
        - selection_mode
        - source
        - dimension_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'
        selection_mode:
          type:
            - string
            - 'null'
          enum:
            - single
            - multiple
            - null
          description: >
            `null` pour une question ouverte ; `single` ou `multiple` pour une

            question avec choix. Distingue notamment les deux variantes
            semi-ouvertes.
        source:
          $ref: '#/components/schemas/QuestionSource'
        choices:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/ConfiguredChoice'
        dimension_id:
          type: string
          minLength: 1
          maxLength: 128
          description: Exactement une dimension.
        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: >-
        Une dimension est couverte après 1 intention distincte en essential, 2
        en balanced ou 3 en deep, dans la limite des intentions disponibles. Des
        questions proches peuvent partager une intention. Un conflit de données
        non résolu garde la dimension bloquée. La réussite globale exige aussi
        des informations de réussite conclues et une couverture moyenne des
        dimensions contributives de 0.00, 0.80 ou 1.00 respectivement, sauf
        décision explicite du client. Ce n'est pas un pourcentage de questions
        posées.
    CompletionRole:
      type: string
      enum:
        - blocking
        - contributing
        - optional
      description: >-
        Rôle dans la qualification globale : les données des dimensions blocking
        doivent être conclues ; une dimension blocking sans donnée ne bloque pas
        seule la réussite. Les dimensions contributing participent au seuil
        moyen du niveau. Les dimensions optional n'imposent pas de seuil de
        couverture, mais les informations de réussite configurées restent
        exigées, sauf exclusion ou décision explicite du client.
    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`.

        Pour `semi_open`, `selection_mode` précise si un ou plusieurs choix sont
        permis en plus du complément libre.
    QuestionSource:
      type: string
      enum:
        - user
        - llm_generated
      description: Provenance éditoriale de la question.
    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 domaine de qualification mobilier
      value:
        request_id: req_1005
        state: published
        configuration_version: cfg_00013
        draft_revision: null
        published_at: '2026-08-28T14:02:00Z'
        domain:
          name: Qualification mobilier
        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: 15
          candidates_per_call: 1
          order_strength: 0.35
        dimensions:
          - 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
            selection_mode: single
            source: llm_generated
            dimension_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
            selection_mode: null
            source: user
            dimension_id: so_budget
            active: true
            choices: []
          - id: q_delai
            text: À quelle période souhaitez-vous être livré ?
            type: single_choice
            selection_mode: single
            source: user
            dimension_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: >-
        Réponse 401 possible au niveau de l'application. Une clé absente ou
        invalide est généralement refusée en 403 par la passerelle, sans
        enveloppe métier garantie.
      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: >-
        Accès refusé. La passerelle peut renvoyer 403 pour une clé absente,
        invalide, expirée, révoquée ou dépourvue du scope requis, sans enveloppe
        métier garantie.
      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: Zelinqa API key
      description: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.