openapi.yaml

openapi: 3.1.0
info:
  title: RAG Service API
  version: "1.0.0"
  summary: Public API for querying and managing the RAG service.
  description: |
    Versioned public API for external applications integrating with the RAG
    service. All `/api/v1/*` endpoints require an `X-API-Key` header. In
    multi-user deployments, each API key resolves to exactly one user
    workspace; queries, uploads, jobs, conversations, and deletes stay inside
    that workspace boundary.
servers:
  - url: http://127.0.0.1:5000
    description: Local development server
tags:
  - name: Health
    description: Service readiness and runtime status.
  - name: Models
    description: Available providers and model selections.
  - name: Query
    description: RAG question answering.
  - name: Files
    description: RAG file upload and indexing.
  - name: Knowledge Bases
    description: Catalog and lifecycle management for isolated knowledge bases.
  - name: Chat Agents
    description: Named presets bundling a provider, model, knowledge bases, and prompt for query-by-agent_id.
  - name: Conversation History
    description: Session-auth endpoints for the persistent per-workspace conversation transcript.
  - name: OCR
    description: Text extraction from images and PDFs.
  - name: Speech
    description: Audio transcription and text-to-speech.
security:
  - ApiKeyAuth: []
paths:
  /api/v1/health:
    get:
      tags:
        - Health
      operationId: getApiV1Health
      summary: Get service health
      description: |
        Returns runtime health for model configuration, settings, embeddings,
        cache and ChromaDB.
      parameters:
        - $ref: "#/components/parameters/KnowledgeBaseId"
      responses:
        "200":
          description: Service health payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              examples:
                healthy:
                  value:
                    status: healthy
                    model_configuration_ready: true
                    settings_ready: true
                    embeddings_ready: true
                    cache_enabled: true
                    database_ready: true
                    tracked_files_count: 3
                    indexed_files_count: 3
                    stale_index_files_count: 0
                    needs_rebuild: false
                    system_ready: true
                    stt_ready: true
                    tts_ready: true
                    voice_provider: openai-compatible
                    ocr_ready: false
                    ocr_provider: ""
                    state_backend: memory
                    queue_backend: inline
                    redis_ready: true
                    queue_ready: true
                    queue_depth: 0
                    active_jobs_count: 0
                    collection: documents_user_123
                    documents_count: 128
        "401":
          $ref: "#/components/responses/Unauthorized"
  /metrics:
    get:
      tags:
        - Health
      operationId: getMetrics
      summary: Prometheus metrics
      description: |
        Returns service metrics in Prometheus text exposition format.
        No authentication required. Useful for monitoring dashboards
        (Grafana, Prometheus scraper, etc.).

        Metrics include:
        - Query count and latency histogram
        - Retrieval latency histogram
        - Cache hit/miss counters
        - HTTP request count and latency
        - Active queries gauge
        - Memory usage
        - Uptime
      responses:
        "200":
          description: Prometheus text exposition format metrics.
          content:
            text/plain:
              schema:
                type: string
              examples:
                sample:
                  value: |
                    # HELP rag_queries_total Total RAG queries.
                    # TYPE rag_queries_total counter
                    rag_queries_total{status="success"} 142.0
                    rag_queries_total{status="error"} 5.0
                    # HELP rag_query_duration_seconds RAG query duration.
                    # TYPE rag_query_duration_seconds histogram
                    ...
  /api/v1/models:
    get:
      tags:
        - Models
      operationId: listApiV1Models
      summary: List available models
      description: |
        Returns enabled built-in and custom OpenAI-compatible models that can
        be used in `/api/v1/query`.
      responses:
        "200":
          description: Available models grouped as a flat list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelsResponse"
              examples:
                default:
                  value:
                    default_provider: mistral
                    default_model: mistral-medium
                    default_value: mistral:mistral-medium
                    models:
                      - id: mistral-medium
                        name: mistral-medium (Mistral AI)
                        provider: mistral
                        provider_name: Mistral AI
                        value: mistral:mistral-medium
                        is_default: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          description: Model provider configuration is missing or invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                modelConfigurationError:
                  value:
                    error: "No models configured in app/default_providers.json."
                    status: model_configuration_error
                    provider_config_file: app/default_providers.json
                    configure_url: /admin/config
  /api/v1/query:
    post:
      tags:
        - Query
      operationId: postApiV1Query
      summary: Query the RAG service
      description: |
        Answers a question using one or more authorized knowledge bases, up to
        the runtime limit returned by the knowledge-base list endpoint. The
        service embeds the question once, retrieves candidates from every
        selected collection, deduplicates them, and applies one global ranking.
        By default the response is JSON. When `stream` is `true`, the response body is progressive
        `text/plain` output. Set `stream_format` to `ndjson` to receive one
        structured JSON event per line, including final context sources.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryRequest"
              examples:
                nonStreaming:
                  value:
                    query: What are the main points of the document?
                    provider: mistral
                    model: mistral-medium
                    conversation_id: chat-20260616-demo
                    knowledge_base_ids:
                      - default
                      - kb_11111111111111111111111111111111
                    response_language: auto
                    temperature: 0.3
                    k: 5
                streaming:
                  value:
                    query: Summarize the document.
                    stream: true
                structuredStreaming:
                  value:
                    query: Summarize the document.
                    stream: true
                    stream_format: ndjson
      responses:
        "200":
          description: Query answer. JSON when `stream` is false, text or NDJSON events when `stream` is true.
          headers:
            X-Knowledge-Base-Ids:
              description: Comma-separated knowledge base IDs used by the query.
              schema:
                type: string
            X-Knowledge-Base-Id:
              description: Present for text streaming only when exactly one KB was selected.
              schema:
                $ref: "#/components/schemas/KnowledgeBaseId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResponse"
              examples:
                answer:
                  value:
                    answer: Response generated by the model.
                    model: mistral-medium
                    provider: mistral
                    provider_name: Mistral AI
                    conversation_id: chat-20260616-demo
                    knowledge_base_ids:
                      - default
                      - kb_11111111111111111111111111111111
                    response_language: auto
                    context:
                      - text: Chunk retrieved from document...
                        metadata:
                          source: app/uploads/workspaces/user_123/demo.pdf
                          chunk_id: 0
                          knowledge_base_id: default
                          knowledge_base_name: General
                          chunk_length: 924
                    sources:
                      - filename: demo.pdf
                        source_type: pdf
                        chunk_id: 0
                        knowledge_base_id: default
                        knowledge_base_name: General
                        snippet: Chunk retrieved from document...
                    usage: null
            text/plain:
              schema:
                type: string
              examples:
                streamedText:
                  value: Response generated progressively...
            application/x-ndjson:
              schema:
                type: string
                description: Newline-delimited QueryStreamEvent JSON objects.
              examples:
                streamedEvents:
                  value: |
                     {"type":"meta","model":"mistral-medium","provider":"mistral","provider_name":"Mistral AI","response_language":"auto","conversation_id":"chat-20260616-demo","knowledge_base_ids":["default"],"knowledge_base_id":"default"}
                     {"type":"token","text":"Progressive "}
                     {"type":"token","text":"response..."}
                     {"type":"done","answer":"Progressive response...","model":"mistral-medium","provider":"mistral","provider_name":"Mistral AI","response_language":"auto","conversation_id":"chat-20260616-demo","knowledge_base_ids":["default"],"knowledge_base_id":"default","context":[],"sources":[],"usage":null}
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/KnowledgeBaseNotFound"
        "409":
          $ref: "#/components/responses/KnowledgeBaseConflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/v1/knowledge-bases:
    get:
      tags:
        - Knowledge Bases
      operationId: listApiV1KnowledgeBases
      summary: List knowledge bases authorized to the API key
      description: Requires at least one of `query`, `ingest`, or `kb_manage`.
      responses:
        "200":
          description: Authorized knowledge bases with file/source statistics.
          content:
            application/json:
              schema:
                type: object
                required: [knowledge_bases, limits]
                properties:
                  knowledge_bases:
                    type: array
                    items:
                      $ref: "#/components/schemas/KnowledgeBase"
                  limits:
                    type: object
                    required: [max_query_knowledge_bases, max_knowledge_bases]
                    properties:
                      max_query_knowledge_bases:
                        type: integer
                        minimum: 1
                      max_knowledge_bases:
                        type: integer
                        minimum: 1
                        description: Total workspace capacity, including the default knowledge base.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags:
        - Knowledge Bases
      operationId: createApiV1KnowledgeBase
      summary: Create a knowledge base
      description: Requires `kb_manage`. The creating key receives access; other keys are unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KnowledgeBaseCreateInput"
      responses:
        "201":
          description: Knowledge base created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBase"
        "400":
          $ref: "#/components/responses/ValidationError"
        "409":
          description: Duplicate name or configured KB limit reached.
  /api/v1/knowledge-bases/{knowledge_base_id}:
    parameters:
      - $ref: "#/components/parameters/KnowledgeBaseIdPath"
    get:
      tags:
        - Knowledge Bases
      operationId: getApiV1KnowledgeBase
      summary: Get one authorized knowledge base
      responses:
        "200":
          description: Knowledge base.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBase"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags:
        - Knowledge Bases
      operationId: updateApiV1KnowledgeBase
      summary: Rename or describe a knowledge base
      description: Requires `kb_manage`; IDs, status, paths and default role are immutable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KnowledgeBaseUpdateInput"
      responses:
        "200":
          description: Updated knowledge base.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBase"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Duplicate name or deletion already in progress.
    delete:
      tags:
        - Knowledge Bases
      operationId: deleteApiV1KnowledgeBase
      summary: Start asynchronous cascade deletion
      description: |
        Requires `kb_manage`. An authorized default KB always returns 409;
        an unauthorized default target is hidden with 404.
      responses:
        "202":
          description: Cascade deletion job accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncJobResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Default KB, deleting KB, or active jobs prevent deletion.
  /api/v1/agents:
    get:
      tags:
        - Chat Agents
      operationId: listApiV1Agents
      summary: List chat agents visible to the API key
      description: |
        Requires `query` or `agent_manage`. Only agents whose
        `knowledge_base_ids` are a subset of the key's allowlist are returned.
      responses:
        "200":
          description: Visible agents and workspace limits.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatAgentsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags:
        - Chat Agents
      operationId: createApiV1Agent
      summary: Create a chat agent
      description: Requires `agent_manage`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatAgentCreateInput"
      responses:
        "201":
          description: Agent created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatAgent"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/KnowledgeBaseNotFound"
        "409":
          description: KB limit, agent count limit, or duplicate name.
  /api/v1/agents/options:
    get:
      tags:
        - Chat Agents
      operationId: getApiV1AgentOptions
      summary: Models, knowledge bases, prompts, and limits for the API key
      description: |
        Requires `query` or `agent_manage`. Useful for building agent
        create/edit forms in external clients.
      responses:
        "200":
          description: Available options.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatAgentOptionsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /api/v1/agents/{agent_id}:
    parameters:
      - $ref: "#/components/parameters/AgentIdPath"
    get:
      tags:
        - Chat Agents
      operationId: getApiV1Agent
      summary: Get one chat agent
      description: |
        Requires `query` or `agent_manage`. An agent referencing a KB outside
        the key's allowlist is hidden with 404.
      responses:
        "200":
          description: Agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatAgent"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/ChatAgentNotFound"
    patch:
      tags:
        - Chat Agents
      operationId: updateApiV1Agent
      summary: Update a chat agent
      description: |
        Requires `agent_manage`. All fields are optional; only provided fields
        change. At least one field is required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatAgentUpdateInput"
      responses:
        "200":
          description: Updated agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatAgent"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/ChatAgentNotFound"
        "409":
          description: KB limit or duplicate name.
    delete:
      tags:
        - Chat Agents
      operationId: deleteApiV1Agent
      summary: Delete a chat agent
      description: Requires `agent_manage`.
      responses:
        "200":
          description: Agent deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatAgentDeleteResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/ChatAgentNotFound"
  /api/v1/conversations/{conversation_id}:
    delete:
      tags:
        - Query
      operationId: deleteApiV1Conversation
      summary: Clear conversation memory
      description: |
        Removes the conversation memory associated with the supplied
        `conversation_id`. Repeat `knowledge_base_ids` for the KB selection
        whose plural conversation namespace must be cleared.
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            minLength: 8
            maxLength: 80
            pattern: "^[A-Za-z0-9][A-Za-z0-9_-]*$"
          example: chat-20260616-demo
        - $ref: "#/components/parameters/KnowledgeBaseIds"
      responses:
        "200":
          description: Conversation memory reset result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - conversation_id
                  - cleared
                  - knowledge_base_ids
                properties:
                  conversation_id:
                    type: string
                  cleared:
                    type: boolean
                  knowledge_base_ids:
                    type: array
                    minItems: 1
                    uniqueItems: true
                    items:
                      $ref: "#/components/schemas/KnowledgeBaseId"
                  knowledge_base_id:
                    allOf:
                      - $ref: "#/components/schemas/KnowledgeBaseId"
                    description: Present only when exactly one knowledge base was selected.
              examples:
                pluralSelectionCleared:
                  value:
                    conversation_id: chat-20260616-demo
                    cleared: true
                    knowledge_base_ids:
                      - default
                      - kb_11111111111111111111111111111111
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/KnowledgeBaseNotFound"
        "409":
          $ref: "#/components/responses/KnowledgeBaseConflict"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/conversations:
    get:
      tags:
        - Conversation History
      operationId: listConversations
      summary: List persisted conversations
      description: |
        Lists conversations persisted to the per-workspace SQLite history store
        for the logged-in workspace. Conversations with zero messages are
        hidden. Session-authenticated (browser login cookie + CSRF); not part of
        the API-key v1 contract. Returns an empty list when history is
        disabled (`RAG_CONVERSATION_HISTORY_ENABLED=0`).
      security:
        - SessionAuth: []
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - archived
        - name: archived
          in: query
          required: false
          description: "Sets `status` when `status` is omitted. `true` -> archived, `false` -> active."
          schema:
            type: string
            enum:
              - "true"
              - "false"
      responses:
        "200":
          description: Paginated conversation list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - conversations
                  - pagination
                properties:
                  conversations:
                    type: array
                    items:
                      $ref: "#/components/schemas/ConversationRecord"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/conversations/{history_id}:
    get:
      tags:
        - Conversation History
      operationId: getConversation
      summary: Get a conversation record
      description: |
        Returns the full conversation record by its server-side UUID
        `history_id`. Session-authenticated. Returns `404` when the id is not a
        UUID, history is disabled, or the conversation belongs to another
        workspace.
      security:
        - SessionAuth: []
      parameters:
        - name: history_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Conversation record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationRecord"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/ServerError"
    patch:
      tags:
        - Conversation History
      operationId: updateConversation
      summary: Rename and/or archive a conversation
      description: |
        Updates the `title` and/or `archived` flag of a conversation.
        Session-authenticated. `title` is max 120 chars; `archived` is a boolean.
      security:
        - SessionAuth: []
      parameters:
        - name: history_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 120
                archived:
                  type: boolean
              additionalProperties: false
      responses:
        "200":
          description: Updated conversation record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationRecord"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - Conversation History
      operationId: deleteConversation
      summary: Hard-delete a conversation
      description: |
        Permanently deletes a conversation and all its messages and turn
        records. Session-authenticated. Returns `{"deleted": false}` when
        history is disabled.
      security:
        - SessionAuth: []
      parameters:
        - name: history_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - deleted
                properties:
                  deleted:
                    type: boolean
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/conversations/{history_id}/messages:
    get:
      tags:
        - Conversation History
      operationId: listConversationMessages
      summary: List messages for a conversation
      description: |
        Returns messages for a conversation with backward cursor pagination.
        Messages are returned oldest-first within the requested window.
        Session-authenticated.
      security:
        - SessionAuth: []
      parameters:
        - name: history_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: before_sequence
          in: query
          required: false
          description: Fetch messages with `sequence <` this value (cursor from a previous page).
          schema:
            type: integer
            minimum: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        "200":
          description: Paginated messages.
          content:
            application/json:
              schema:
                type: object
                required:
                  - messages
                  - next_cursor
                  - limit
                properties:
                  messages:
                    type: array
                    items:
                      $ref: "#/components/schemas/ConversationMessage"
                  next_cursor:
                    description: "Sequence of the oldest message in the window, to pass as `before_sequence` for the previous page. `null` when there are no older messages."
                    oneOf:
                      - type: integer
                      - type: "null"
                  limit:
                    type: integer
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/v1/files:
    post:
      tags:
        - Files
      operationId: postApiV1Files
      summary: Upload and index a document
      description: |
        Uploads a PDF, TXT, or Markdown document and indexes it into the RAG
        knowledge base of the user workspace resolved by the API key. The
        request requires an API key with `ingest` scope. Public integrations
        should use workspace API keys via `X-API-Key`. Synchronous processing remains the default for
        backward compatibility; pass `async=true` to receive a job id and poll
        `/api/v1/jobs/{job_id}`.
      parameters:
        - name: async
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: When true, save the upload and process indexing as a background job.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: PDF, TXT, or Markdown file to index.
                relative_path:
                  type: string
                  description: Optional safe relative path, including the filename.
                knowledge_base_id:
                  $ref: "#/components/schemas/KnowledgeBaseId"
      responses:
        "200":
          description: File uploaded and indexed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileUploadResponse"
              examples:
                uploaded:
                  value:
                    message: documento.pdf uploaded and indexed
                    filename: documento.pdf
                    source_type: pdf
                    chunks: 18
        "202":
          description: File upload accepted for async processing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncJobResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/UploadUnauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/v1/audio:
    post:
      tags:
        - Speech
        - Files
      operationId: postApiV1Audio
      summary: Upload, transcribe, and index audio
      description: Uploads an audio file, transcribes it with the configured STT provider, and indexes the transcript. Optional multipart language overrides the configured STT language for this request. Synchronous processing remains the default for backward compatibility; pass async=true to receive a job id and poll /api/v1/jobs/{job_id}.
      parameters:
        - name: async
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: When true, save the upload and process transcription/indexing as a background job.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file to transcribe and index.
                language:
                  type: string
                  description: Optional STT language hint, such as it or en. Empty or omitted enables fallback to configured language/autodetect.
                relative_path:
                  type: string
                  description: Optional safe relative path, including the filename.
                knowledge_base_id:
                  $ref: "#/components/schemas/KnowledgeBaseId"
      responses:
        "200":
          description: Audio transcribed and indexed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AudioUploadResponse"
        "202":
          description: Audio upload accepted for async transcription and indexing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncJobResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/UploadUnauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/v1/jobs/{job_id}:
    get:
      tags:
        - Jobs
      operationId: getApiV1Job
      summary: Get async job status
      description: |
        Returns the current state, errors, and final result for async ingest,
        rebuild, sync, and knowledge-base deletion jobs. Ingest jobs require
        `ingest` plus current target authorization. Delete jobs require
        `kb_manage` and are visible only to the API key that initiated DELETE.
        That key can keep polling after deletion cleanup removes the target
        from its allowlist.
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
          description: Job id returned by an async endpoint.
      responses:
        "200":
          description: Job status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatus"
        "401":
          $ref: "#/components/responses/UploadUnauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/v1/ocr:
    post:
      tags:
        - OCR
      operationId: postApiV1Ocr
      summary: Extract text from an image or PDF
      description: |
        Extracts text from an uploaded image or PDF. For PDFs, the service first
        tries the standard text parser and only uses the configured OCR provider
        when the parser returns no text. This endpoint does not index content in
        the RAG knowledge base.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Image or PDF file to extract text from.
      responses:
        "200":
          description: Extracted text.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OcrExtractResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/v1/tts:
    post:
      tags:
        - Speech
      operationId: postApiV1Tts
      summary: Synthesize text to speech
      description: Converts text to audio using the configured TTS provider.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TtsRequest"
      responses:
        "200":
          description: Binary audio.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/v1/files/{filename}:
    delete:
      tags:
        - Files
      operationId: deleteApiV1File
      summary: Delete an indexed file
      description: |
        Removes a file from the RAG knowledge base. This deletes ChromaDB chunks
        associated with the file source, removes the administrative file index
        entry, deletes the uploaded file when it is still present under the
        upload folder, and clears the retrieval cache.
      parameters:
        - name: filename
          in: path
          required: true
          schema:
            type: string
          example: documento.pdf
        - $ref: "#/components/parameters/KnowledgeBaseId"
      responses:
        "200":
          description: File removed from the knowledge base.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileDeleteResponse"
              examples:
                deleted:
                  value:
                    message: documento.pdf removed from knowledge base
                    filename: documento.pdf
                    source: app/uploads/workspaces/user_123/documento.pdf
                    chunks_deleted: 18
                    file_deleted: true
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/UploadUnauthorized"
        "404":
          description: File is not registered in the administrative file index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                 notFound:
                   value:
                     error: Indexed file not found
                     status: not_found
                     field: filename
        "500":
          $ref: "#/components/responses/ServerError"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: User/workspace API key configured from `/admin/api-keys`. `RAG_API_KEY` remains available as a legacy global compatibility key.
    SessionAuth:
      type: apiKey
      in: cookie
      name: session
      description: |
        Browser session cookie issued after login. Used only by the
        `/api/conversations/*` history-management endpoints, which back the
        in-app history drawer and require CSRF protection.
  parameters:
    KnowledgeBaseId:
      name: knowledge_base_id
      in: query
      required: false
      description: Omit or use `default` for the legacy-compatible default KB.
      schema:
        $ref: "#/components/schemas/KnowledgeBaseId"
    KnowledgeBaseIds:
      name: knowledge_base_ids
      in: query
      required: false
      description: |
        Repeat this parameter for every selected KB. Omission targets the
        legacy default conversation namespace rather than a plural namespace.
      style: form
      explode: true
      schema:
        type: array
        minItems: 1
        uniqueItems: true
        items:
          $ref: "#/components/schemas/KnowledgeBaseId"
    KnowledgeBaseIdPath:
      name: knowledge_base_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/KnowledgeBaseId"
    AgentIdPath:
      name: agent_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/ChatAgentId"
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing:
              value:
                error: Missing or invalid API key
                status: unauthorized
    UploadUnauthorized:
      description: Missing credentials or API key without ingest scope.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing:
              value:
                error: Upload credentials missing or invalid
                status: unauthorized
    Forbidden:
      description: API key is valid but lacks the required scope.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missingScope:
              value:
                error: "API key missing required scope: speech"
                status: forbidden
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing:
              value:
                error: Job non trovato
                status: not_found
    NotFoundError:
      description: Conversation or resource not found, or history is disabled.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            notFound:
              value:
                error: Conversation not found
                status: not_found
    ValidationError:
      description: Request payload failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            invalidQuery:
              value:
                error: query must have at least 3 characters
                status: validation_error
                field: query
    KnowledgeBaseNotFound:
      description: A selected knowledge base is missing or not authorized to the API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missingOrUnauthorized:
              value:
                error: Knowledge base non trovata
                status: knowledge_base_not_found
    KnowledgeBaseConflict:
      description: A selected knowledge base cannot currently serve queries.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            deleting:
              value:
                error: Knowledge base in eliminazione
                status: knowledge_base_deleting
            deleteFailed:
              value:
                error: Eliminazione knowledge base fallita
                status: knowledge_base_delete_failed
    ChatAgentNotFound:
      description: Chat agent does not exist or is outside the API key's KB allowlist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missingOrUnauthorized:
              value:
                error: Agent non trovato
                status: chat_agent_not_found
    RateLimited:
      description: Too many requests in the configured time window.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            limited:
              value:
                error: Rate limit exceeded
                retry_after: 42
                status: rate_limited
    ServerError:
      description: Internal error or upstream provider error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            serverError:
              value:
                error: Upstream provider unavailable
                status: server_error
  schemas:
    KnowledgeBaseId:
      type: string
      pattern: "^(default|kb_[0-9a-f]{32})$"
      default: default
    KnowledgeBaseCreateInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        description:
          type: string
          maxLength: 1000
      additionalProperties: false
    KnowledgeBaseUpdateInput:
      type: object
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        description:
          type: string
          maxLength: 1000
      additionalProperties: false
    KnowledgeBase:
      type: object
      required:
        - id
        - name
        - description
        - is_default
        - status
        - created_at
        - updated_at
        - stats
      properties:
        id:
          $ref: "#/components/schemas/KnowledgeBaseId"
        name:
          type: string
        description:
          type: string
        is_default:
          type: boolean
        status:
          type: string
          enum: [active, deleting, delete_failed]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        delete_error:
          type: string
        stats:
          type: object
          required: [tracked_files, indexed_files, chunks, data_sources]
          properties:
            tracked_files:
              type: integer
              minimum: 0
            indexed_files:
              type: integer
              minimum: 0
            chunks:
              type: integer
              minimum: 0
            data_sources:
              type: integer
              minimum: 0
    ChatAgentId:
      type: string
      pattern: "^agent_[0-9a-f]{32}$"
    ChatAgentPromptRef:
      type: object
      oneOf:
        - maxProperties: 0
        - required: [id, scope]
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 200
        scope:
          type: string
          enum: [personal, shared]
      additionalProperties: false
      description: >
        System prompt reference. An empty object means the agent has no system
        prompt; otherwise both id and scope are required.
    ChatAgentPromptRefInput:
      oneOf:
        - $ref: "#/components/schemas/ChatAgentPromptRef"
        - type: "null"
      description: >
        Optional system prompt reference. Omit the field on create, or send
        null or an empty object to create or update an agent without a prompt.
    ChatAgentAvailabilityIssue:
      type: object
      required: [code, field, message]
      properties:
        code:
          type: string
          examples:
            - model_unavailable
            - knowledge_base_missing
            - knowledge_base_inactive
            - knowledge_base_limit_exceeded
            - prompt_missing
            - prompt_inactive
        field:
          type: string
        message:
          type: string
    ChatAgent:
      type: object
      required:
        - id
        - name
        - description
        - provider_id
        - model_id
        - knowledge_base_ids
        - prompt_ref
        - created_at
        - updated_at
        - available
        - issues
      properties:
        id:
          $ref: "#/components/schemas/ChatAgentId"
        name:
          type: string
        description:
          type: string
        provider_id:
          type: string
        model_id:
          type: string
        knowledge_base_ids:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/KnowledgeBaseId"
        prompt_ref:
          $ref: "#/components/schemas/ChatAgentPromptRef"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        available:
          type: boolean
          description: True when the agent can currently run (no availability issues).
        issues:
          type: array
          items:
            $ref: "#/components/schemas/ChatAgentAvailabilityIssue"
    ChatAgentsResponse:
      type: object
      required: [agents, limits, capabilities]
      properties:
        agents:
          type: array
          items:
            $ref: "#/components/schemas/ChatAgent"
        limits:
          type: object
          required: [max_chat_agents, max_query_knowledge_bases]
          properties:
            max_chat_agents:
              type: integer
              minimum: 0
            max_query_knowledge_bases:
              type: integer
              minimum: 1
        capabilities:
          type: object
          required: [can_manage]
          properties:
            can_manage:
              type: boolean
    ChatAgentCreateInput:
      type: object
      required:
        - name
        - provider_id
        - model_id
        - knowledge_base_ids
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        description:
          type: string
          maxLength: 500
        provider_id:
          type: string
          minLength: 1
          maxLength: 120
        model_id:
          type: string
          minLength: 1
          maxLength: 200
        knowledge_base_ids:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/KnowledgeBaseId"
        prompt_ref:
          $ref: "#/components/schemas/ChatAgentPromptRefInput"
      additionalProperties: false
    ChatAgentUpdateInput:
      type: object
      minProperties: 1
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        description:
          type: string
          maxLength: 500
        provider_id:
          type: string
          minLength: 1
          maxLength: 120
        model_id:
          type: string
          minLength: 1
          maxLength: 200
        knowledge_base_ids:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/KnowledgeBaseId"
        prompt_ref:
          $ref: "#/components/schemas/ChatAgentPromptRefInput"
      additionalProperties: false
    ChatAgentDeleteResponse:
      type: object
      required: [ok]
      properties:
        ok:
          type: boolean
    ChatAgentOptionsResponse:
      type: object
      required:
        - models
        - default_provider
        - default_model
        - knowledge_bases
        - prompts
        - limits
        - capabilities
      properties:
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelInfo"
        default_provider:
          type: string
        default_model:
          type: string
        knowledge_bases:
          type: array
          items:
            $ref: "#/components/schemas/KnowledgeBase"
        prompts:
          type: array
          items:
            type: object
            required: [id, name, scope, is_active]
            properties:
              id:
                type: string
              name:
                type: string
              scope:
                type: string
                enum: [personal, shared]
              is_active:
                type: boolean
        limits:
          type: object
          required: [max_chat_agents, max_query_knowledge_bases]
          properties:
            max_chat_agents:
              type: integer
              minimum: 0
            max_query_knowledge_bases:
              type: integer
              minimum: 1
        capabilities:
          type: object
          required: [can_manage]
          properties:
            can_manage:
              type: boolean
    ErrorResponse:
      type: object
      required:
        - error
        - status
      properties:
        error:
          type: string
        status:
          type: string
          examples:
            - validation_error
            - unauthorized
            - rate_limited
            - server_error
            - model_configuration_error
        field:
          type: string
          description: Field that failed validation, when available.
        retry_after:
          type: integer
          minimum: 1
          description: Seconds to wait before retrying after rate limiting.
        provider_config_file:
          type: string
          description: Provider model configuration file path.
        configure_url:
          type: string
          description: Admin page used to fix runtime or model configuration.
      additionalProperties: true
    JobStatus:
      type: object
      required:
        - id
        - status
        - message
        - processed
        - total
        - errors
      properties:
        id:
          type: string
        type:
          type: string
          examples:
            - file_upload
            - audio_upload
            - rebuild_index
            - data_source_sync
            - delete_knowledge_base
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
        status:
          type: string
          examples:
            - queued
            - running
            - completed
            - completed_with_errors
            - failed
        message:
          type: string
        processed:
          type: integer
          minimum: 0
        total:
          type: integer
          minimum: 0
        current_file:
          type: string
        filename:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              error:
                type: string
        result:
          nullable: true
          type: object
          additionalProperties: true
        started_at:
          type: number
        finished_at:
          nullable: true
          type: number
    AsyncJobResponse:
      allOf:
        - $ref: "#/components/schemas/JobStatus"
        - type: object
          required:
            - job_id
          properties:
            job_id:
              type: string
    HealthResponse:
      type: object
      required:
        - status
        - model_configuration_ready
        - settings_ready
        - embeddings_ready
        - cache_enabled
        - database_ready
      properties:
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
        status:
          type: string
          enum:
            - healthy
            - degraded
            - unhealthy
        model_configuration_ready:
          type: boolean
        settings_ready:
          type: boolean
        embeddings_ready:
          type: boolean
        cache_enabled:
          type: boolean
        database_ready:
          type: boolean
        tracked_files_count:
          type: integer
          minimum: 0
        indexed_files_count:
          type: integer
          minimum: 0
        stale_index_files_count:
          type: integer
          minimum: 0
        needs_rebuild:
          type: boolean
        system_ready:
          type: boolean
          description: True when the system has model config, settings, database, a non-stale index and at least one indexed chunk.
        stt_ready:
          type: boolean
        tts_ready:
          type: boolean
        voice_provider:
          type: string
        ocr_ready:
          type: boolean
        ocr_provider:
          type: string
        state_backend:
          type: string
          enum:
            - memory
            - redis
          description: Runtime state backend for rate limit, cache, conversation memory, and job state.
        queue_backend:
          type: string
          enum:
            - inline
            - redis
          description: Long-running job execution backend.
        redis_ready:
          type: boolean
          description: True when Redis-backed runtime dependencies are available, or Redis is not required.
        queue_ready:
          type: boolean
          description: True when the configured queue backend is ready.
        queue_depth:
          type: integer
          minimum: 0
        active_jobs_count:
          type: integer
          minimum: 0
        redis_error:
          type: string
        queue_error:
          type: string
        index_profile:
          type: object
          additionalProperties: true
        collection:
          type: string
          examples:
            - documents
        documents_count:
          type: integer
          minimum: 0
        model_configuration_error:
          type: string
        provider_config_file:
          type: string
        settings_error:
          type: string
        embeddings_error:
          type: string
        database_error:
          type: string
      additionalProperties: true
    ModelsResponse:
      type: object
      required:
        - models
      properties:
        default_provider:
          type: string
          description: Provider selected by runtime configuration when a query omits provider.
          examples:
            - mistral
        default_model:
          type: string
          description: Model selected by runtime configuration when a query omits model.
          examples:
            - mistral-medium
        default_value:
          type: string
          description: Compact `provider:model` value for the runtime default.
          examples:
            - mistral:mistral-medium
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelInfo"
    ModelInfo:
      type: object
      required:
        - id
        - name
        - provider
        - provider_name
        - value
      properties:
        id:
          type: string
          examples:
            - mistral-medium
        name:
          type: string
          examples:
            - mistral-medium (Mistral AI)
        provider:
          type: string
          examples:
            - mistral
        provider_name:
          type: string
          examples:
            - Mistral AI
        value:
          type: string
          description: Compact UI value in `provider:model` format.
          examples:
            - mistral:mistral-medium
        is_default:
          type: boolean
          description: True when this model is the configured runtime default.
          examples:
            - true
    QueryRequest:
      type: object
      required:
        - query
      properties:
        agent_id:
          $ref: "#/components/schemas/ChatAgentId"
          description: |
            Resolve provider, model, knowledge bases, and prompt from a chat
            agent preset. When provided, `provider`, `model`,
            `knowledge_base_ids`, `knowledge_base_id`, `system_prompt_id`, and
            `system_prompt_scope` must be omitted or a 400 error with status
            `agent_conflicting_params` is returned.
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
          deprecated: true
          description: Legacy single-KB selector. Do not combine with knowledge_base_ids.
        knowledge_base_ids:
          type: array
          minItems: 1
          uniqueItems: true
          description: |
            Ordered set of authorized active knowledge bases queried together.
            The runtime maximum is returned as
            `limits.max_query_knowledge_bases` by the knowledge-base list
            endpoint.
          items:
            $ref: "#/components/schemas/KnowledgeBaseId"
        query:
          type: string
          minLength: 3
          maxLength: 2000
          description: Natural-language question.
        provider:
          type: string
          description: Provider id returned by `/api/v1/models`.
        model:
          type: string
          description: Model id returned by `/api/v1/models`.
        conversation_id:
          type: string
          minLength: 8
          maxLength: 80
          pattern: "^[A-Za-z0-9][A-Za-z0-9_-]*$"
          description: Optional conversation memory id. Reuse it across requests to enable follow-up context.
        system_prompt_id:
          type: string
          description: Optional personal or shared system prompt identifier.
        client_context:
          $ref: "#/components/schemas/ClientContext"
        response_language:
          type: string
          default: auto
          description: Output language policy for the RAG answer prompt. Omit or use `auto` to answer in the question language; use `it` or `en` to force Italian or English.
          examples:
            - auto
            - it
            - en
        stream:
          type: boolean
          default: false
          description: Return streaming output when true.
        stream_format:
          type: string
          enum:
            - text
            - ndjson
          default: text
          description: Streaming response format. `ndjson` emits one structured JSON event per line.
        temperature:
          type: number
          minimum: 0
          maximum: 1
        k:
          type: integer
          minimum: 1
          maximum: 50
          description: Number of retrieved chunks.
        persist_history:
          type: boolean
          default: false
          description: |
            Opt in to the durable per-workspace SQLite history store. Both
            `conversation_id` and `turn_id` are required. When `false`, the
            turn stays in warm memory only and `history_status` is
            `not_requested`.
        turn_id:
          type: string
          minLength: 1
          maxLength: 80
          pattern: "^[A-Za-z0-9][A-Za-z0-9_-]*$"
          description: |
            Stable id for the turn. Reuse it on retries to receive the persisted
            result with `replayed: true` without regenerating. Required for
            `persist_history` to take effect; without it the response carries
            `history_status: client_turn_id_required`.
        parent_turn_id:
          type: string
          maxLength: 80
          pattern: "^[A-Za-z0-9][A-Za-z0-9_-]*$"
          description: |
            `turn_id` of the previous visible turn; enforces a linear chain.
            Omit (or send `null`) for the first turn of a conversation.
        regenerate_lost_result:
          type: boolean
          default: false
          description: |
            Explicit recovery for `volatile_result_lost`. When true, the
            server replaces the expired ready draft and regenerates the same
            `turn_id`. Never set this automatically on an ordinary retry.
      additionalProperties: false
    ClientContext:
      type: object
      description: Optional external-client site/page metadata added to the prompt only. It is not indexed and is not returned in sources.
      properties:
        site_name:
          type: string
          maxLength: 120
        page_title:
          type: string
          maxLength: 180
        page_url:
          type: string
          maxLength: 500
          format: uri
        post_type:
          type: string
          maxLength: 80
        locale:
          type: string
          maxLength: 40
        instructions:
          type: string
          maxLength: 1200
      additionalProperties: false
    QueryResponse:
      type: object
      required:
        - knowledge_base_ids
        - answer
        - model
        - provider
        - context
        - usage
      properties:
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
          description: Present only when exactly one knowledge base was selected.
        knowledge_base_ids:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/KnowledgeBaseId"
        answer:
          type: string
        model:
          type: string
        provider:
          type: string
        provider_name:
          type: string
        agent_id:
          $ref: "#/components/schemas/ChatAgentId"
          description: Present only when the query was resolved from a chat agent.
        agent_name:
          type: string
          description: Present only when the query was resolved from a chat agent.
        response_language:
          type: string
          description: Effective output language policy used in the RAG prompt.
          examples:
            - auto
        conversation_id:
          type: string
          description: Present only when the request supplied a conversation_id.
        context:
          type: array
          items:
            $ref: "#/components/schemas/ContextItem"
        sources:
          type: array
          items:
            $ref: "#/components/schemas/PublicSource"
        usage:
          oneOf:
            - type: object
              additionalProperties: true
            - type: "null"
        history_status:
          type: string
          enum:
            - saved
            - not_requested
            - disabled
            - client_turn_id_required
            - error
          description: |
            Outcome of the durable history turn. `saved` = persisted;
            `not_requested` = `persist_history` was false; `disabled` = feature
            flag off; `client_turn_id_required` = `turn_id` missing (memory
            updated, nothing persisted); `error` = persistence failed.
        history_saved:
          type: boolean
          description: Convenience boolean; `true` only when `history_status` is `saved`.
    ContextItem:
      type: object
      required:
        - text
        - metadata
      properties:
        text:
          type: string
        metadata:
          type: object
          description: Includes knowledge_base_id, knowledge_base_name, and knowledge_base_origins provenance for federated retrieval.
          additionalProperties: true
    PublicSource:
      type: object
      required:
        - filename
        - source_type
        - snippet
      properties:
        filename:
          type: string
        source_type:
          type: string
          examples:
            - pdf
            - text
            - markdown
            - audio
        chunk_id:
          oneOf:
            - type: string
            - type: integer
        page:
          oneOf:
            - type: string
            - type: integer
        score:
          type: number
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
        knowledge_base_name:
          type: string
        knowledge_base_origins:
          type: array
          items:
            type: object
            additionalProperties: true
        snippet:
          type: string
    FileUploadResponse:
      type: object
      required:
        - message
        - filename
        - chunks
        - source_type
      properties:
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
        message:
          type: string
        filename:
          type: string
        chunks:
          type: integer
          minimum: 0
        source_type:
          type: string
          enum:
            - pdf
            - text
            - markdown
        ocr_used:
          type: boolean
          description: True when a scanned/empty PDF was indexed through OCR fallback.
    AudioUploadResponse:
      type: object
      required:
        - message
        - filename
        - chunks
        - source_type
        - transcript
      properties:
        knowledge_base_id:
          $ref: "#/components/schemas/KnowledgeBaseId"
        message:
          type: string
        filename:
          type: string
        chunks:
          type: integer
          minimum: 0
        source_type:
          type: string
          const: audio
        transcript:
          type: string
        language_hint:
          type: string
          description: STT language hint used for the request, or empty when autodetect was used.
    OcrExtractResponse:
      type: object
      required:
        - filename
        - text
        - method
        - ocr_used
      properties:
        filename:
          type: string
        text:
          type: string
        method:
          type: string
          enum:
            - parsed
            - ocr
        ocr_used:
          type: boolean
    TtsRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 4000
        voice:
          type: string
        format:
          type: string
          enum:
            - mp3
            - wav
            - opus
            - aac
            - flac
    FileDeleteResponse:
      type: object
      required:
        - message
        - filename
        - source
        - chunks_deleted
        - file_deleted
      properties:
        message:
          type: string
        filename:
          type: string
        source:
          type: string
        chunks_deleted:
          type: integer
          minimum: 0
        file_deleted:
          type: boolean
    ConversationRecord:
      type: object
      description: |
        A persisted conversation record from the per-workspace SQLite history
        store. Identified by its server-side UUID `id`; the `client_conversation_id`
        is the id supplied by the client.
      required:
        - id
        - client_conversation_id
        - scope_kind
        - title
        - status
        - message_count
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Server-side UUID used by the history-management endpoints.
        client_conversation_id:
          type: string
          description: Id originally supplied by the client.
        scope_key:
          type: string
          description: Internal unique key used by the warm memory layer.
        scope_kind:
          type: string
          enum:
            - default
            - kb
            - multi
        title:
          type: string
          maxLength: 120
        status:
          type: string
          enum:
            - active
            - archived
        agent_id:
          type: string
        agent_name:
          type: string
        provider_id:
          type: string
        model_id:
          type: string
        prompt_ref:
          type: object
          additionalProperties: true
        response_language:
          type: string
        summary:
          type: string
        summary_version:
          type: integer
        summary_through_sequence:
          type: integer
        message_count:
          type: integer
          minimum: 0
        payload_bytes:
          type: integer
          minimum: 0
        last_turn_id:
          oneOf:
            - type: string
            - type: "null"
        has_incomplete_turn:
          type: boolean
          description: True when the conversation has at least one turn not yet completed.
        created_at:
          type: number
          description: Unix timestamp (seconds).
        updated_at:
          type: number
          description: Unix timestamp (seconds).
        archived_at:
          oneOf:
            - type: number
            - type: "null"
    ConversationMessage:
      type: object
      description: A single message (user or assistant) in a persisted conversation.
      required:
        - id
        - conversation_id
        - turn_id
        - role
        - content
        - sequence
        - created_at
      properties:
        id:
          type: integer
        conversation_id:
          type: string
          format: uuid
        turn_id:
          type: string
        role:
          type: string
          enum:
            - user
            - assistant
        message_type:
          type: string
          description: Content kind, e.g. `text` or a Code Interpreter marker.
        content:
          type: string
        sequence:
          type: integer
          minimum: 1
          description: Monotonic position within the conversation; used as cursor.
        sources:
          type: array
          description: Safe source list (no local paths or admin download URLs).
          items:
            type: object
            additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        payload_bytes:
          type: integer
          minimum: 0
        created_at:
          type: number
          description: Unix timestamp (seconds).
    Pagination:
      type: object
      description: Page-based pagination envelope.
      required:
        - page
        - per_page
        - total
        - page_count
        - has_prev
        - has_next
      properties:
        page:
          type: integer
          minimum: 1
        per_page:
          type: integer
          minimum: 1
        total:
          type: integer
          minimum: 0
        page_count:
          type: integer
          minimum: 1
        has_prev:
          type: boolean
        has_next:
          type: boolean