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

# Apply session events

> Apply conversation context or client-known data without selecting a new question.



## OpenAPI

````yaml /openapi.yaml post /v1/sessions/{session_id}/events
openapi: 3.1.0
info:
  version: 1.0.0
  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
  title: NBQ Engine — API V1
  summary: Public runtime and question-bank configuration contract.
  description: >-
    NBQ Engine's public V1 contract, served from https://api.zelinqa.ai. The
    server resolves the tenant, NBQ instance, and scopes from the API key. Never
    send trusted identity headers from the client. Mutations use
    Idempotency-Key, and existing-session mutations also use state_version.
servers:
  - url: https://api.zelinqa.ai
security:
  - ApiKeyAuth: []
tags:
  - name: sessions
    description: Create, advance, inspect, and close server-side NBQ conversations.
  - name: configuration
    description: Read, edit, audit, compile, and publish a question-bank configuration.
paths:
  /v1/sessions/{session_id}/events:
    post:
      tags:
        - sessions
      summary: Apply session events
      description: >-
        Apply conversation context or client-known data without selecting a new
        question.
      operationId: applySessionEvents
      parameters:
        - $ref: '#/components/parameters/SessionId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionEventsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStateResponse'
          description: Successful response.
        '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
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 128
  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'
        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:
          messages:
            $ref: '#/components/schemas/ConversationMessageDelta'
    ClientUpdates:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        data:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/DataClientUpdate'
        sub_objectives:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/SubObjectiveOverrideUpdate'
        objective:
          $ref: '#/components/schemas/ObjectiveOverrideUpdate'
    PublicQuestionState:
      type: object
      additionalProperties: false
      required:
        - outcomes
      properties:
        outcomes:
          type: array
          items:
            $ref: '#/components/schemas/QuestionOutcomeRecord'
    PublicTargetState:
      type: object
      additionalProperties: false
      required:
        - kind
        - coverage
      properties:
        kind:
          type: string
          enum:
            - data
            - exploration
        status:
          type: string
          enum:
            - tentative
            - confirmed
            - conflicted
            - not_applicable
        value: {}
        coverage:
          type: number
          minimum: 0
          maximum: 1
    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
      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
      properties:
        state_version:
          type: integer
          minimum: 0
        engine_version:
          type: string
        api_version:
          type: string
          const: '1.0'
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
        - details
      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'
    DataClientUpdate:
      oneOf:
        - $ref: '#/components/schemas/SetDataUpdate'
        - $ref: '#/components/schemas/UnsetDataUpdate'
        - $ref: '#/components/schemas/NotApplicableDataUpdate'
    SubObjectiveOverrideUpdate:
      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'
        outcome:
          $ref: '#/components/schemas/QuestionOutcome'
        source:
          type: string
          enum:
            - client
            - inferred
        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
        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
    Candidate:
      type: object
      additionalProperties: false
      required:
        - rank
        - question_id
        - text
        - type
        - choices
        - target_ids
      properties:
        rank:
          type: integer
          minimum: 1
          maximum: 10
        question_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/CandidateChoice'
        target_ids:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 128
    ErrorCode:
      type: string
      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
      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'
        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:
          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
    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
    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
    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
    StructuredAnswer:
      type: object
      additionalProperties: false
      required:
        - choice_ids
      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
    SubObjectiveOverrideValue:
      type: string
      enum:
        - achieved
        - not_achieved
        - excluded
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Unauthorized.
    InsufficientScope:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: InsufficientScope.
    UnknownSession:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: UnknownSession.
    SessionMutationConflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: SessionMutationConflict.
    CompiledArtifactUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: CompiledArtifactUnavailable.
    InvalidChoice:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: InvalidChoice.
    IdempotencyContention:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: IdempotencyContention.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: NBQ API key

````