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

# Get the next questions

> Apply the previous turn, update progress, and return the best eligible question candidates.



## OpenAPI

````yaml /openapi.yaml post /v1/sessions/{session_id}/next
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}/next:
    post:
      tags:
        - sessions
      summary: Get the next questions
      description: >-
        Apply the previous turn, update progress, and return the best eligible
        question candidates.
      operationId: nextQuestions
      parameters:
        - $ref: '#/components/parameters/SessionId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NextRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NextResponse'
          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/NextUnprocessable'
        '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:
    NextRequest:
      type: object
      additionalProperties: false
      required:
        - state_version
      properties:
        state_version:
          type: integer
          minimum: 0
        previous_turn:
          $ref: '#/components/schemas/PreviousTurn'
        context_update:
          $ref: '#/components/schemas/ContextUpdate'
        client_updates:
          $ref: '#/components/schemas/ClientUpdates'
        selection:
          $ref: '#/components/schemas/SelectionOptions'
    NextResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - session_id
        - decision_id
        - action
        - stop_reason
        - candidates
        - progress
        - turn_count
        - turns_remaining
        - warnings
        - degraded
        - degraded_reasons
        - versions
      properties:
        request_id:
          type: string
        session_id:
          type: string
        decision_id:
          type:
            - string
            - 'null'
        action:
          type: string
          enum:
            - ask
            - stop
        stop_reason:
          oneOf:
            - $ref: '#/components/schemas/StopReason'
            - type: 'null'
        candidates:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Candidate'
        progress:
          $ref: '#/components/schemas/ProgressView'
        turn_count:
          type: integer
          minimum: 0
        turns_remaining:
          type: integer
          minimum: 0
        warnings:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/SelectionWarning'
        degraded:
          type: boolean
        degraded_reasons:
          type: array
          uniqueItems: true
          items:
            type: string
            enum:
              - missing_user_text
              - summary_only_context
              - semantic_service_unavailable
              - unresolved_previous_turn
        versions:
          $ref: '#/components/schemas/VersionInfo'
    PreviousTurn:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        decision_id:
          type: string
          minLength: 1
          maxLength: 128
        question_id:
          type: string
          minLength: 1
          maxLength: 128
        outcome:
          $ref: '#/components/schemas/QuestionOutcome'
        assistant_text:
          type: string
          minLength: 1
          maxLength: 8000
        user_text:
          type: string
          minLength: 1
          maxLength: 8000
        structured_answer:
          $ref: '#/components/schemas/StructuredAnswer'
        message_id:
          type: string
          minLength: 1
          maxLength: 128
    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'
    SelectionOptions:
      type: object
      additionalProperties: false
      properties:
        candidate_count:
          type: integer
          minimum: 1
          maximum: 10
        sub_objectives:
          $ref: '#/components/schemas/SubObjectiveSelection'
        allowed_question_types:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/QuestionType'
        required_target_ids:
          type: array
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 128
        excluded_question_ids:
          type: array
          maxItems: 500
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 128
    StopReason:
      type: string
      enum:
        - no_question_available
    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
    ProgressView:
      type: object
      additionalProperties: false
      required:
        - objective
        - sub_objectives
      properties:
        objective:
          $ref: '#/components/schemas/ObjectiveProgress'
        sub_objectives:
          type: array
          items:
            $ref: '#/components/schemas/SubObjectiveProgress'
    SelectionWarning:
      type: string
      enum:
        - max_turns_reached
        - objective_achieved
        - eligibility_exhausted_fallback
        - constraints_relaxed
    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
    QuestionOutcome:
      type: string
      enum:
        - asked_answered
        - asked_no_answer
        - refused
    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
    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
    SubObjectiveSelection:
      type: object
      additionalProperties: false
      required:
        - ids
        - mode
      properties:
        ids:
          type: array
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 128
        mode:
          type: string
          enum:
            - restrict
            - prefer
    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
    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
    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
    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
    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.
    NextUnprocessable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: NextUnprocessable.
    IdempotencyContention:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: IdempotencyContention.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: NBQ API key

````