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

# Create a session

> Create a server-side conversation session pinned to the active published configuration.



## OpenAPI

````yaml /openapi.yaml post /v1/sessions
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:
    post:
      tags:
        - sessions
      summary: Create a session
      description: >-
        Create a server-side conversation session pinned to the active published
        configuration.
      operationId: createSession
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStateResponse'
          description: Successful response.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '410':
          $ref: '#/components/responses/CompiledArtifactUnavailable'
        '422':
          $ref: '#/components/responses/InvalidChoice'
        '503':
          $ref: '#/components/responses/IdempotencyContention'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 128
  schemas:
    SessionCreateRequest:
      type: object
      additionalProperties: false
      properties:
        client_reference:
          type: string
          minLength: 1
          maxLength: 128
        max_turns:
          type: integer
          minimum: 1
          maximum: 100
        initial_history:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/InitialHistoryItem'
    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'
    InitialHistoryItem:
      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
    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
    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
    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
    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
    ObjectiveOverrideValue:
      type: string
      enum:
        - achieved
        - not_achieved
    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.
    IdempotencyConflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: IdempotencyConflict.
    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

````