> ## 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. # Appliquer un contexte ou une mise à jour sans sélectionner de question > Même réducteur que `/next`, sans la phase de sélection. Sert à rattraper des messages qui n'ont pas transité par Zelinqa, synchroniser une donnée déjà connue du système appelant, corriger une valeur, ou piloter une dimension. La décision en attente reste en attente, sauf si le contexte fourni permet de la résoudre sans ambiguïté. ## OpenAPI ````yaml /openapi.fr.yaml post /v1/sessions/{session_id}/events 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/sessions/{session_id}/events: post: tags: - sessions summary: Appliquer un contexte ou une mise à jour sans sélectionner de question description: > Même réducteur que `/next`, sans la phase de sélection. Sert à rattraper des messages qui n'ont pas transité par Zelinqa, synchroniser une donnée déjà connue du système appelant, corriger une valeur, ou piloter une dimension. La décision en attente reste en attente, sauf si le contexte fourni permet de la résoudre sans ambiguïté. operationId: applySessionEvents parameters: - $ref: '#/components/parameters/SessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionEventsRequest' examples: donnee_connue_du_client: summary: Le CRM connaît déjà la donnée, inutile de poser la question value: state_version: 2 client_updates: data: - id: company_size value: 120 dimension_exclue: summary: L'intégrateur retire une étape du parcours value: state_version: 2 client_updates: dimensions: - id: so_livraison operation: exclude resume_intermediaire: summary: Échanges hors Zelinqa résumés par l'agent hôte value: state_version: 3 context_update: mode: summary text: >- Le visiteur a précisé qu'il emménage en mars et qu'il mesure la pièce ce week-end. responses: '200': description: État public après application des mises à jour. content: application/json: schema: $ref: '#/components/schemas/SessionStateResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '404': $ref: '#/components/responses/UnknownSession' '409': $ref: '#/components/responses/SessionMutationConflict' '410': $ref: '#/components/responses/CompiledArtifactUnavailable' '422': $ref: '#/components/responses/InvalidChoice' '503': $ref: '#/components/responses/IdempotencyContention' components: parameters: SessionId: name: session_id in: path required: true schema: type: string minLength: 1 maxLength: 128 description: Identifiant opaque de session attribué par Zelinqa à la création. IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 description: > 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. schemas: SessionEventsRequest: type: object additionalProperties: false required: - state_version properties: state_version: type: integer minimum: 0 context_update: $ref: '#/components/schemas/ContextUpdate' client_updates: $ref: '#/components/schemas/ClientUpdates' anyOf: - required: - context_update - required: - client_updates 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' ContextUpdate: oneOf: - $ref: '#/components/schemas/ConversationSummary' - $ref: '#/components/schemas/ConversationMessageDelta' discriminator: propertyName: mode mapping: summary: '#/components/schemas/ConversationSummary' messages: '#/components/schemas/ConversationMessageDelta' description: > Contexte apparu depuis le dernier appel Zelinqa. Le client choisit un résumé compact ou le delta ordonné des messages ; il ne renvoie jamais l'historique déjà traité. ClientUpdates: type: object additionalProperties: false minProperties: 1 description: >- Mises à jour explicites du système appelant, prioritaires sur l'inférence. properties: data: type: array maxItems: 100 items: $ref: '#/components/schemas/DataClientUpdate' dimensions: type: array maxItems: 100 items: $ref: '#/components/schemas/DimensionOverrideUpdate' objective: $ref: '#/components/schemas/ObjectiveOverrideUpdate' 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 dimension 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 - dimensions properties: objective: $ref: '#/components/schemas/ObjectiveProgress' dimensions: type: array items: $ref: '#/components/schemas/DimensionProgress' 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 ConversationSummary: type: object additionalProperties: false required: - mode - text properties: mode: type: string const: summary text: type: string minLength: 1 maxLength: 16000 ConversationMessageDelta: type: object additionalProperties: false required: - mode - messages properties: mode: type: string const: messages messages: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/ConversationMessage' description: Messages nouveaux, dans l'ordre conversationnel. DataClientUpdate: oneOf: - $ref: '#/components/schemas/SetDataUpdate' - $ref: '#/components/schemas/UnsetDataUpdate' - $ref: '#/components/schemas/NotApplicableDataUpdate' description: > Le client n'envoie jamais de statut. `set` produit une valeur confirmée avec la priorité de preuve maximale ; `unset` retire la valeur courante ; `not_applicable` satisfait une information de réussite sans lui donner de valeur, par exemple une donnée sans objet pour ce visiteur. DimensionOverrideUpdate: oneOf: - type: object additionalProperties: false required: - id - operation - status properties: id: type: string minLength: 1 maxLength: 128 operation: type: string const: set status: type: string enum: - achieved - not_achieved - type: object additionalProperties: false required: - id - operation properties: id: type: string minLength: 1 maxLength: 128 operation: type: string const: exclude - type: object additionalProperties: false required: - id - operation properties: id: type: string minLength: 1 maxLength: 128 operation: type: string const: clear ObjectiveOverrideUpdate: oneOf: - type: object additionalProperties: false required: - operation - status properties: operation: type: string const: set status: $ref: '#/components/schemas/ObjectiveOverrideValue' - type: object additionalProperties: false required: - operation properties: operation: type: string const: clear 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 Zelinqa. 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 Zelinqa. 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 dimensions pondérée par leur rôle de complétion. Les dimensions exclus sortent du dénominateur. client_override: oneOf: - $ref: '#/components/schemas/ObjectiveClientOverrideView' - type: 'null' effective_status: $ref: '#/components/schemas/ProgressStatus' DimensionProgress: 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/DimensionClientOverrideView' - 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 la dimension 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 : Zelinqa 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. selection_mode: $ref: '#/components/schemas/QuestionSelectionMode' description: | Présent pour `semi_open` afin d'indiquer si l'appelant accepte un ou plusieurs `choice_ids`. Absent pour les autres types. 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 ConversationMessage: type: object additionalProperties: false required: - role description: | Message du delta de contexte. Une `structured_answer` portée par un message utilisateur est mappée déterministement, sans LLM, comme pour `previous_turn` — elle exige donc `question_id` : sans lui, la requête est rejetée en `invalid_previous_turn`. Un `question_id` connu du corpus rend les cibles de cette question vérifiables par l'extraction, même hors décision en attente. properties: role: type: string enum: - user - assistant message_id: type: string minLength: 1 maxLength: 128 question_id: type: string minLength: 1 maxLength: 128 text: type: string minLength: 1 maxLength: 8000 structured_answer: $ref: '#/components/schemas/StructuredAnswer' description: > Réponse structurée rapportée dans le delta. Obligatoirement accompagnée de `question_id` (le schéma ne porte pas de if/then : la règle est appliquée par le runtime, code `invalid_previous_turn`). occurred_at: type: string format: date-time anyOf: - required: - text - required: - structured_answer SetDataUpdate: type: object additionalProperties: false required: - id - value properties: id: type: string minLength: 1 maxLength: 128 operation: type: string const: set default: set value: description: > Valeur validée contre le schéma publié de l'information de réussite. Une chaîne, un nombre, un booléen ou une liste de ces valeurs ; jamais un objet, forme que l'extraction ne saurait produire ni corriger. oneOf: - type: string - type: number - type: boolean - type: array items: oneOf: - type: string - type: number - type: boolean UnsetDataUpdate: type: object additionalProperties: false required: - id - operation properties: id: type: string minLength: 1 maxLength: 128 operation: type: string const: unset NotApplicableDataUpdate: type: object additionalProperties: false required: - id - operation properties: id: type: string minLength: 1 maxLength: 128 operation: type: string const: not_applicable ObjectiveOverrideValue: type: string enum: - achieved - not_achieved 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 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. DimensionClientOverrideView: type: object additionalProperties: false required: - status properties: status: $ref: '#/components/schemas/DimensionOverrideValue' 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`. Pour `semi_open`, `selection_mode` précise si un ou plusieurs choix sont permis en plus du complément libre. 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 QuestionSelectionMode: type: string enum: - single - multiple StructuredAnswer: type: object additionalProperties: false required: - choice_ids description: > Réponse à une question à choix. Le mapping choix vers information de réussite est déterministe et compilé à la publication : aucun appel LLM n'est effectué pour l'interpréter. properties: choice_ids: type: array minItems: 1 maxItems: 50 uniqueItems: true items: type: string minLength: 1 maxLength: 128 free_text: type: string minLength: 1 maxLength: 4000 description: Complément libre, autorisé uniquement pour une question `semi_open`. DimensionOverrideValue: type: string enum: - achieved - not_achieved - excluded description: > `achieved` force la dimension à 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: >- 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 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 SessionMutationConflict: description: Conflit de version optimiste ou réutilisation d'une clé d'idempotence. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: state_version_conflict: summary: La session a été modifiée entre-temps value: code: state_version_conflict message: La session a été modifiée depuis votre dernière lecture. request_id: req_9003 details: supplied_state_version: 7 current_state_version: 8 idempotency_key_reused: summary: Même clé, corps différent value: code: idempotency_key_reused message: Cette clé d'idempotence est déjà associée à une autre requête. request_id: req_9004 details: idempotency_key: next-ses01J8Z-turn-4 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 InvalidChoice: description: Une valeur fournie n'appartient pas au schéma ou aux choix publiés. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: 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 IdempotencyContention: description: > La clé d'idempotence n'a pas pu être réservée après deux tentatives, à cause d'un cycle anormal de requêtes concurrentes portant la même clé. Ce n'est **pas** une erreur du client et ce n'est pas un conflit : réessayer après un court délai a des chances d'aboutir. À distinguer de `idempotency_key_reused`, qui est définitif pour ce couple clé/corps. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: 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 securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: Zelinqa API key description: >- Envoyez la clé API dans Authorization: Bearer . 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.