components:
  schemas:
    handlers.JobNotFoundResponse:
      properties:
        error:
          description: Human readable error message
          type: string
        job_id:
          description: The job identifier that was requested
          type: string
      type: object
    handlers.MQTTActiveItem:
      description: Lightweight view of an active MQTT subscription item.
      properties:
        broker:
          type: string
        conversationId:
          type: string
        id:
          type: string
        name:
          type: string
        roomId:
          type: string
        scope:
          type: string
        status:
          type: string
        subscriptions:
          type: object
      type: object
    handlers.MQTTConnectResponse:
      description: Response for MQTT connect action.
      properties:
        connected:
          type: boolean
        finished:
          type: string
        source_id:
          type: string
      type: object
    handlers.MQTTListActiveResponse:
      description: Response envelope listing active MQTT subscriptions.
      properties:
        count:
          type: integer
        items:
          items:
            $ref: '#/components/schemas/handlers.MQTTActiveItem'
          type: array
          uniqueItems: false
      type: object
    handlers.MQTTReconnectResponse:
      description: Response for MQTT reconnect action.
      properties:
        finished:
          type: string
        reconnected:
          type: boolean
        source_id:
          type: string
      type: object
    handlers.MQTTSourceRequest:
      description: Represents a simple request where knowing the context source is
        sufficient.
      properties:
        deleteSource:
          description: only for unsubscribe (optional)
          type: boolean
        sourceId:
          type: string
      type: object
    handlers.MQTTSubscribeRequest:
      description: Represents a request for subscribing an MQTT Topic & connect it
        with a context source.
      properties:
        autoStart:
          description: default true
          type: boolean
        config:
          $ref: '#/components/schemas/mqttingest.MQTTConfig'
        conversationId:
          description: required for CONVERSATION
          type: string
        name:
          description: human-readable
          type: string
        parser:
          $ref: '#/components/schemas/mqttingest.ParserCfg'
        roomId:
          description: required for ROOM
          type: string
        scope:
          description: '"CONVERSATION" | "ROOM"'
          type: string
      type: object
    handlers.MQTTUnsubscribeResponse:
      description: Response for MQTT unsubscribe action.
      properties:
        deleted:
          type: boolean
        disconnected:
          type: boolean
        finished:
          type: string
        source_id:
          type: string
      type: object
    handlers.component:
      description: Human‑readable status and minimal telemetry about a dependency
        (e.g., PostgreSQL, Milvus, Unstructured, Feature Flags).
      properties:
        checked_url:
          type: string
        endpoint:
          type: string
        errors:
          items:
            type: string
          type: array
          uniqueItems: false
        http_status:
          type: integer
        latency_ms:
          type: integer
        message:
          type: string
        ok:
          type: boolean
      type: object
    handlers.loadavg:
      description: Optional system load averages; may be omitted on platforms without
        /proc/loadavg.
      properties:
        5m:
          type: number
        15m:
          type: number
        1m:
          type: number
      type: object
    handlers.memBrief:
      description: Selected memory counters derived from Go runtime statistics.
      properties:
        alloc_bytes:
          type: integer
        heap_inuse:
          type: integer
        last_pause_ns:
          type: integer
        num_gc:
          type: integer
        sys_bytes:
          type: integer
      type: object
    handlers.metrics:
      description: Lightweight process metrics to aid debugging of degraded states.
      properties:
        loadavg:
          $ref: '#/components/schemas/handlers.loadavg'
        mem:
          $ref: '#/components/schemas/handlers.memBrief'
        num_goroutines:
          type: integer
        requests_last_60s:
          type: integer
      type: object
    handlers.readyResponse:
      description: Readiness summary with per‑component status and lightweight metrics.
      properties:
        components:
          additionalProperties:
            $ref: '#/components/schemas/handlers.component'
          type: object
        metrics:
          $ref: '#/components/schemas/handlers.metrics'
        status:
          description: '"ready" | "degraded" | "down"'
          type: string
        timestamp:
          type: string
        uptime_sec:
          type: integer
      type: object
    managers.Bucket:
      properties:
        avg:
          type: number
        count:
          type: integer
        end:
          description: exclusive
          type: string
        max:
          type: number
        min:
          type: number
        start:
          description: inclusive
          type: string
        sum:
          type: number
      type: object
    models.AddAssistantMessageRequest:
      description: Request body for adding an assistant message to a conversation.
      properties:
        message:
          type: string
        metadata:
          description: for rag_citations
          type: object
        request_id:
          type: string
        token_count:
          type: integer
      type: object
    models.AddAuditEventRequest:
      description: Request body for adding an event to the audit trail.
      properties:
        action:
          description: The kind of action that caused the audit event.
          type: string
          x-enum-varnames:
          - ActionCreateConversation
          - ActionRemoveConversation
          - ActionJoinConversation
          - ActionLeaveConversation
          - ActionQueryRAG
          - ActionUploadDocument
          - ActionDeleteDocument
          - ActionAddDocumentToRoom
          - ActionRemoveDocumentFromRoom
          - ActionRegisterGateway
          - ActionForgetGateway
          - ActionRegisterMCPServer
          - ActionUnregisterMCPServer
          - ActionCallMCPTool
          - ActionCreateUser
          - ActionDeleteUser
          - ActionFirstLogin
          - ActionSystemHealthDegraded
          - ActionSystemHealthDown
          - ActionSystemHealthRecovered
        details:
          type: object
        target_id:
          type: string
        target_type:
          description: The object category targeted by an action that caused the audit
            event.
          type: string
          x-enum-varnames:
          - TargetConversation
          - TargetDocument
          - TargetGateway
          - TargetUser
          - TargetMCPServer
          - TargetService
        user_id:
          type: string
      type: object
    models.AddMessageContentPart:
      description: Content model of a multimodal message as part of a conversation.
      properties:
        image_url:
          $ref: '#/components/schemas/models.ImageURL'
        text:
          type: string
        type:
          type: string
      type: object
    models.AddMessageRequest:
      description: Request body for adding a user message to a conversation.
      properties:
        content:
          items:
            $ref: '#/components/schemas/models.AddMessageContentPart'
          type: array
          uniqueItems: false
        gateway_id:
          type: string
        model_id:
          type: string
        request_id:
          type: string
        sender:
          type: string
        streaming:
          type: boolean
        user_id:
          type: string
      type: object
    models.AddUserToRoomRequest:
      description: Request body for adding a user to a Factory 42 knowledge room.
      properties:
        user_role:
          default: USER
          type: string
      type: object
    models.AuditAction:
      description: The kind of action that caused the audit event.
      type: string
      x-enum-varnames:
      - ActionCreateConversation
      - ActionRemoveConversation
      - ActionJoinConversation
      - ActionLeaveConversation
      - ActionQueryRAG
      - ActionUploadDocument
      - ActionDeleteDocument
      - ActionAddDocumentToRoom
      - ActionRemoveDocumentFromRoom
      - ActionRegisterGateway
      - ActionForgetGateway
      - ActionRegisterMCPServer
      - ActionUnregisterMCPServer
      - ActionCallMCPTool
      - ActionCreateUser
      - ActionDeleteUser
      - ActionFirstLogin
      - ActionSystemHealthDegraded
      - ActionSystemHealthDown
      - ActionSystemHealthRecovered
    models.AuditEvent:
      description: Represents an event as part of Factory 42's audit trail.
      properties:
        action:
          $ref: '#/components/schemas/models.AuditAction'
        details:
          type: string
        id:
          type: string
        prev_hash:
          type: string
        request_id:
          type: string
        target_id:
          type: string
        target_type:
          $ref: '#/components/schemas/models.AuditTargetType'
        timestamp:
          type: string
        user_id:
          description: optional, supporting system events w/o user.
          type: string
      type: object
    models.AuditTargetType:
      description: The object category targeted by an action that caused the audit
        event.
      type: string
      x-enum-varnames:
      - TargetConversation
      - TargetDocument
      - TargetGateway
      - TargetUser
      - TargetMCPServer
      - TargetService
    models.CollectionMeta:
      description: Transport-only meta for the Knowledge room's vector collection.
      properties:
        chunks:
          type: integer
        name:
          type: string
        url:
          type: string
      type: object
    models.ContextItem:
      description: Is a single normalized event/document originating from a ContextSource.
        It supports both receipt-style business docs and machine/MQTT time-series
        events.
      properties:
        batch_id:
          type: string
        conversationId:
          type: string
        createdAt:
          type: string
        currency:
          type: string
        dedupHash:
          description: UNIQUE (nullable)
          type: string
        deviceId:
          type: string
        document_id:
          type: string
        grossTotal:
          description: numeric(18,6) mapped to float64
          type: number
        id:
          type: string
        idempotencyKey:
          description: 'Idempotency/deduplication keys:'
          type: string
        kind:
          $ref: '#/components/schemas/models.ContextItemKind'
        merchant:
          description: 'Normalized commerce fields (receipt-style):'
          type: string
        messageId:
          description: UNIQUE (nullable, e.g. MQTT msg id)
          type: string
        metrics:
          description: derived metric key→value map
          type: object
        netTotal:
          type: number
        occurred_at:
          description: event's timestamp, default snake_case
          type: string
        parent_id:
          description: '(25/11/10, 9:11 CET) - parent/child/grouping:'
          type: string
        payload:
          description: 'Full raw payload and optional flat metric map for fast filters:'
          type: object
        productCount:
          type: integer
        quality:
          description: e.g. "good" | "bad" | "uncertain"
          type: string
        roomId:
          type: string
        scope:
          description: 'Enumerates the scope that a context source/item belongs to.
            - CONVERSATION: data is scoped to a single conversation - ROOM:         data
            is scoped to a knowledge room'
          type: string
          x-enum-varnames:
          - ContextScopeConversation
          - ContextScopeRoom
        sensorId:
          type: string
        seriesKey:
          description: 'Time-series/MQTT convenience fields:'
          type: string
        sourceId:
          description: FK -> ContextSource.id
          type: string
        tags:
          items:
            type: string
          type: array
          uniqueItems: false
        taxTotal:
          type: number
        topic:
          type: string
        ttlExpiresAt:
          description: optional TTL
          type: string
      type: object
    models.ContextItemKind:
      description: 'Provides a coarse category of a single item for fast filtering.
        - RECEIPT:         full receipt payload (may include items[]) - RECEIPT_PRODUCT:
        single product line of a receipt - MQTT_EVENT:      one event/message from
        MQTT - GENERIC_JSON:    fallback arbitrary JSON blob'
      type: string
      x-enum-varnames:
      - ContextItemKindReceipt
      - ContextItemKindReceiptProd
      - ContextItemKindMqttEvent
      - ContextItemKindGenericJSON
    models.ContextScope:
      description: 'Enumerates the scope that a context source/item belongs to. -
        CONVERSATION: data is scoped to a single conversation - ROOM:         data
        is scoped to a knowledge room'
      type: string
      x-enum-varnames:
      - ContextScopeConversation
      - ContextScopeRoom
    models.ContextSource:
      description: Represents a logical data source configured by a user. It can be
        attached either to a conversation or to a knowledge room (mutually exclusive).
      properties:
        config:
          description: 'Transport/parser configuration (broker, topic, qos, mapping,
            …) or import meta:'
          type: object
        conversationId:
          description: non-nil iff scope=CONVERSATION
          type: string
        createdAt:
          type: string
        createdBy:
          description: userId
          type: string
        errorMessage:
          description: set when Status==ERROR
          type: string
        id:
          type: string
        items:
          description: 'Optional denormalized relation; usually not preloaded by stores:'
          items:
            $ref: '#/components/schemas/models.ContextItem'
          type: array
          uniqueItems: false
        lastIngestAt:
          description: when items were last ingested
          type: string
        name:
          description: human-friendly display name
          type: string
        parser:
          description: persisted as jsonb
          type: object
        roomId:
          description: non-nil iff scope=ROOM
          type: string
        scope:
          $ref: '#/components/schemas/models.ContextScope'
        status:
          $ref: '#/components/schemas/models.ContextStatus'
        type:
          $ref: '#/components/schemas/models.ContextSourceType'
        updatedAt:
          type: string
      type: object
    models.ContextSourceType:
      description: 'Describes how the context was ingested or provided. - RECEIPT:
        structured purchase receipt(s) - MQTT:    machine/time-series events via MQTT
        - MANUAL:  user-provided/manual JSON context'
      type: string
      x-enum-varnames:
      - ContextSourceGeneric
      - ContextSourceWebhook
      - ContextSourceUpload
      - ContextSourceTelemetry
      - ContextSourceReceipt
      - ContextSourceMQTT
      - ContextSourceManual
      - ContextSourceReceiptProducts
    models.ContextStatus:
      description: 'Indicates the current state of a source (ingestion pipeline).
        - ACTIVE: ingesting/usable - PAUSED: temporarily disabled - ERROR:  ingestion
        failed; see errorMessage'
      type: string
      x-enum-varnames:
      - ContextStatusActive
      - ContextStatusPaused
      - ContextStatusError
    models.Conversation:
      description: Represents a multi-turn conversation in Factory 42, e.g. chat history
        in a knowledge room. Contains the history of messages, model configuration
        and references to the knowledge room (if any).
      properties:
        createdAt:
          description: Creation timestamp
          type: string
        grammar:
          type: string
        id:
          description: Conversation UUID
          type: string
        lastMessageAt:
          description: Last messagee posted
          type: string
        max_tokens:
          type: integer
        media:
          $ref: '#/components/schemas/models.MediaSource'
        mediaEnabled:
          type: boolean
        messages:
          description: 'Optional: conversation messages'
          items:
            $ref: '#/components/schemas/models.Message'
          type: array
          uniqueItems: false
        model:
          description: ID/name of used model
          type: string
        model_settings:
          description: Arbitrary JSON, e.g. map[string]interface{}
          type: object
        "n":
          type: integer
        participants:
          description: 'Conversations can have multiple participants:'
          items:
            $ref: '#/components/schemas/models.ConversationParticipant'
          type: array
          uniqueItems: false
        rag_enabled:
          description: Whether RAG was enabled
          type: boolean
        room_id:
          description: 'Knowledge Room Context:'
          type: string
        temperature:
          description: 'Model parameters:'
          type: number
        title:
          description: 'Optional: conversation title'
          type: string
        top_k:
          type: integer
        top_p:
          type: number
        updatedAt:
          description: Last update timestamp
          type: string
        userEmail:
          description: Email of user
          type: string
        userId:
          description: ID of user who started the conversation
          type: string
      type: object
    models.ConversationParticipant:
      description: Models a participant in a discussion in a Factory 42 knowledge
        room.
      properties:
        conversation_id:
          type: string
        joined_at:
          default: "2025-07-21T08:23:00Z"
          format: date-time
          type: string
        left_at:
          default: "2025-08-01T09:00:00Z"
          format: date-time
          type: string
        role:
          default: MEMBER
          enum:
          - OWNER
          - MEMBER
          - MODERATOR
          type: string
        user_email:
          type: string
        user_id:
          type: string
        user_name:
          type: string
      type: object
    models.CreateConversationRequest:
      description: Request body for creating a conversation in a Factory 42 knowledge
        room.
      properties:
        media:
          $ref: '#/components/schemas/models.MediaSource'
        model_id:
          default: magistral-small-2506
          type: string
        rag_enabled:
          default: true
          type: boolean
        room_id:
          default: cea83632-8314-487a-9a3a-3c2c471ba21b
          type: string
        title:
          default: Marketing strategy Prometheus
          type: string
      type: object
    models.CreateEmbeddingRequest:
      description: Represents a request for computing embedding vectors from a document.
      properties:
        document_id:
          type: string
        encoding_format:
          type: string
        gateway_id:
          type: string
        input:
          type: string
        metadata:
          type: object
        persist:
          type: boolean
      type: object
    models.CreateRoomRequest:
      description: Request body for creating a Factory 42 knowledge room.
      properties:
        description:
          default: Knowledge room for product vision Prometheus
          type: string
        embedding_model:
          default: granite-embedding-107m-multilingual
          type: string
        name:
          default: PV Prometheus
          type: string
        owner_id:
          default: 24d6c2ff-4b43-4874-9580-e68b9379f582
          type: string
        similarity_search:
          default: cosine
          type: string
      type: object
    models.CreateUserRequest:
      description: Request body for creating a Factory 42 user.
      properties:
        email:
          type: string
        name:
          type: string
        role:
          type: string
          x-enum-varnames:
          - RoleUser
          - RoleAdmin
          - RoleModerator
      type: object
    models.Document:
      description: Represents a document available in Factory 42. Each document is
        uniquely identified and includes metadata such as filename, MIME type, size
        and upload information.
      properties:
        filename:
          description: File name as uploaded
          type: string
        hash:
          description: Content hash (e.g. SHA256)
          type: string
        id:
          description: Document UUID
          type: string
        mimetype:
          description: MIME type (e.g. application/pdf)
          type: string
        path:
          description: File system path
          type: string
        size:
          description: File size in bytes
          type: integer
        uploaded_at:
          description: Upload timestamp (UTC)
          type: string
        uploaded_by:
          description: User ID of uploader
          type: string
      type: object
    models.EmbeddingResponse:
      description: Represents a response for computing embedding vectors from a document.
      properties:
        created_at:
          type: string
        dimensions:
          type: integer
        document_id:
          type: string
        embedding:
          items:
            type: number
          type: array
          uniqueItems: false
        embedding_model:
          type: string
        input:
          type: string
        metadata:
          type: object
        persisted:
          type: boolean
        raw_response:
          type: object
        room_id:
          type: string
      type: object
    models.ErrorResponse:
      description: Standardized error response for Factory 42 API
      properties:
        code:
          description: HTTP status code, e.g. 404
          type: integer
        error_type:
          description: Type information for error classification, e.g. "db_error",
            "json_error", "entity_error"
          type: string
        message:
          description: Human-readable error message
          type: string
      type: object
    models.Gateway:
      description: A registered Gateway instance in Factory 42. Gateways represent
        local AI-serving endpoints that can host multiple models.
      properties:
        active:
          description: Whether the gateway is currently active/reachable.
          example: true
          type: boolean
        created_at:
          description: Creation timestamp of the gateway registration (RFC3339).
          example: "2025-07-25T08:15:30Z"
          type: string
        hostname:
          description: Hostname of the gateway system.
          example: gpu-server-01
          type: string
        id:
          description: Unique identifier for the gateway (UUID).
          example: e61e8ae2-ccba-463f-93e2-672d4e78c2b3
          type: string
        ip_address:
          description: IP address of the gateway system.
          example: 192.168.1.100
          type: string
        last_seen:
          description: Last time the gateway was seen/reported (RFC3339).
          example: "2025-07-25T09:00:00Z"
          type: string
        models:
          description: Models available on this gateway.
          items:
            $ref: '#/components/schemas/models.ModelInfo'
          type: array
          uniqueItems: false
        tags:
          description: Arbitrary tags for classifying the gateway.
          example:
          - '["CUDA"'
          - '"RTX4090"]'
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    models.GatewayModelMapping:
      description: Information about a specific model served by a Gateway.
      properties:
        gateway:
          $ref: '#/components/schemas/models.Gateway'
        modelId:
          type: string
      type: object
    models.GetChunkByIndexResponse:
      description: Complete payload for a single chunk looked up by index within a
        knowledge room document.
      properties:
        ancestor_node_ids:
          example:
          - '["a111..."'
          - '"b222..."]'
          items:
            type: string
          type: array
          uniqueItems: false
        chunk_index:
          example: 96
          type: integer
        chunk_type:
          example: paragraph
          type: string
        content:
          example: Microsoft-Konto anlegen (falls noch nicht vorhanden) …
          type: string
        created_at:
          example: "2025-10-16T17:12:34Z"
          type: string
        doc_id:
          example: 7b1a4642-1831-4d2e-8ff6-d462e507b40e
          type: string
        doc_name:
          example: BZ-14518 Bedienungsanleitung City Lynx, Version 1.2.1.pdf
          type: string
        document_id:
          example: 7b1a4642-1831-4d2e-8ff6-d462e507b40e
          type: string
        embedding_id:
          example: milvus:pk:123456
          type: string
        embedding_model:
          example: Qwen3-Embedding-8B
          type: string
        error_message:
          example: ""
          type: string
        id:
          description: '---- DocumentChunk (complete) ----'
          example: c2f1c9df-6ed8-4a23-8c2c-9a9f4e1b8be0
          type: string
        node_id:
          description: Hierarchical RAG metadata
          example: 0f3c2c20-91b2-4d9a-9a26-5b5cd7b1d9f1
          type: string
        page:
          description: Convenience alias for page (mirrors DocumentChunk.PageNumber)
          example: 11
          type: integer
        para_ordinal:
          example: 4
          type: integer
        room_id:
          description: '---- Context (from route) ----'
          example: 08f2df4d-55be-4003-8c45-c8ff452847d2
          type: string
        room_id_chunk:
          example: 08f2df4d-55be-4003-8c45-c8ff452847d2
          type: string
        section_heading:
          example: Installation
          type: string
        section_number:
          example: "1.2"
          type: string
        section_path:
          example: §1 > 1.2 Installation > Schritt 3
          type: string
        status:
          example: COMPLETED
          type: string
        updated_at:
          example: "2025-10-16T17:12:34Z"
          type: string
      type: object
    models.ImageURL:
      description: Describes the URL of an image in a multi-modal content part.
      properties:
        url:
          description: Image URL
          type: string
      type: object
    models.KnowledgeRoom:
      description: Represents a Factory 42 knowledge room. Each knowledge room is
        uniquely identified and includes metadata such as name, embedding model etc.
      properties:
        created_at:
          description: The creation timestamp (RFC3339)
          type: string
        description:
          description: A description
          type: string
        embedding_model:
          description: The embedding model used in this room
          type: string
        id:
          description: The unique ID of the knowledge room
          type: string
        name:
          description: The short name of the knowledge room
          type: string
        owner_id:
          description: The user ID of the room owner
          type: string
        rag_config:
          description: optional tuning knobs (MMR, λ, β, γ, TopK, ...)
          type: object
        rag_profile:
          $ref: '#/components/schemas/models.RagProfile'
        ragMergeStrategy:
          type: string
        similarity_metric:
          description: The similarity metric used for retrieval
          type: string
        updated_at:
          description: Last updated timestamp (RFC3339)
          type: string
      type: object
    models.KnowledgeRoomResponse:
      description: Enriches KnowledgeRoom with transport-only fields.
      properties:
        collection:
          $ref: '#/components/schemas/models.CollectionMeta'
        created_at:
          description: The creation timestamp (RFC3339)
          type: string
        description:
          description: A description
          type: string
        embedding_model:
          description: The embedding model used in this room
          type: string
        id:
          description: The unique ID of the knowledge room
          type: string
        name:
          description: The short name of the knowledge room
          type: string
        owner_id:
          description: The user ID of the room owner
          type: string
        rag_config:
          description: optional tuning knobs (MMR, λ, β, γ, TopK, ...)
          type: object
        rag_profile:
          $ref: '#/components/schemas/models.RagProfile'
        ragMergeStrategy:
          type: string
        similarity_metric:
          description: The similarity metric used for retrieval
          type: string
        updated_at:
          description: Last updated timestamp (RFC3339)
          type: string
      type: object
    models.MCPBinding:
      description: Data structure for requesting an MCP Binding.
      properties:
        conversationId:
          type: string
        createdAt:
          type: string
        id:
          type: string
        mcpId:
          type: string
        roomId:
          type: string
      type: object
    models.MCPBindingsUpdateRequest:
      description: Data structure representing a request for updating the MCP Server's
        metadata.
      properties:
        conversationIds:
          items:
            type: string
          type: array
          uniqueItems: false
        roomIds:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    models.MCPDiscoveryResult:
      description: Data structure representing the MCP Server discovery result.
      properties:
        prompts:
          items:
            $ref: '#/components/schemas/models.MCPPromptInfo'
          type: array
          uniqueItems: false
        raw:
          type: object
        resources:
          items:
            $ref: '#/components/schemas/models.MCPResourceInfo'
          type: array
          uniqueItems: false
        tools:
          description: name, description, input schema …
          items:
            $ref: '#/components/schemas/models.MCPToolInfo'
          type: array
          uniqueItems: false
      type: object
    models.MCPHealthcheckResult:
      description: Data structure representing the MCP Server healthcheck result.
      properties:
        checkedAt:
          type: string
        details:
          type: string
        latencyMs:
          type: integer
        status:
          description: '"healthy" | "unhealthy" | "unknown"'
          type: string
      type: object
    models.MCPPromptInfo:
      description: Represents a predefined prompt provided by the MCP Server.
      properties:
        description:
          description: Purpose of the prompt
          type: string
        example:
          description: Example invocation or template
          type: string
        name:
          description: Identifier of the prompt
          type: string
        parameters:
          additionalProperties:
            type: string
          description: Key/value for expected parameters
          type: object
      type: object
    models.MCPRefreshToolsResponse:
      description: Response payload for POST /v1/mcp/{id}/tools/refresh.
      properties:
        count:
          description: Number of tools discovered
          type: integer
        server_id:
          description: ID of MCP Server
          type: string
        tools:
          description: Live inventory of tools (name, description, input scheme, optional
            output scheme)
          items:
            $ref: '#/components/schemas/models.MCPToolInfo'
          type: array
          uniqueItems: false
      type: object
    models.MCPResourceInfo:
      description: Represents an external resource accessible by the MCP Server.
      properties:
        description:
          description: Human readable description
          type: string
        metadata:
          additionalProperties:
            type: string
          description: Arbitrary metadata, e.g. path, URI
          type: object
        name:
          description: Name of the resource
          type: string
        type:
          description: file|database|service|other
          type: string
      type: object
    models.MCPServer:
      description: Represents an MCP Server within the Factory 42 framework.
      properties:
        authType:
          description: none|apiKey|bearer|basic|mtls
          type: string
        autoStart:
          type: boolean
        commandArgs:
          items:
            type: string
          type: array
          uniqueItems: false
        commandPath:
          type: string
        createdAt:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        endpoint:
          type: string
        id:
          type: string
        lastCheckedAt:
          type: string
        lastHealth:
          description: healthy|unhealthy|unknown
          type: string
        name:
          type: string
        ownerUserId:
          type: string
        transport:
          description: http|websocket|stdio
          type: string
        updatedAt:
          type: string
      type: object
    models.MCPServerCallToolRequest:
      description: Payload for POST /v1/mcp/{id}/tools/call.
      properties:
        args:
          description: Tool-Argumente (beliebiges JSON)
          type: object
        timeoutMs:
          description: 'optional: Default unten im Handler'
          type: integer
        tool:
          description: Name des Tools (z.B. "read_file")
          type: string
      required:
      - tool
      type: object
    models.MCPServerCallToolResponse:
      description: Standard response of tool call.
      properties:
        durationMs:
          type: integer
        error:
          type: string
        ok:
          type: boolean
        output:
          description: |-
            Output contains the JSON returned by the MCP server (already parsed),
            e.g.: fs-server/read_file:
              { "content": "..." , "truncated": false }
          type: object
      type: object
    models.MCPServerCreateRequest:
      description: Data structure for requesting registration of an MCP Server in
        Factory 42.
      properties:
        authType:
          enum:
          - none
          - apiKey
          - bearer
          - basic
          - mtls
          type: string
        autoStart:
          type: boolean
        commandArgs:
          items:
            type: string
          type: array
          uniqueItems: false
        commandPath:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        endpoint:
          type: string
        name:
          type: string
        transport:
          enum:
          - http
          - websocket
          - stdio
          type: string
      required:
      - endpoint
      - name
      type: object
    models.MCPServerUpdateRequest:
      description: Data structure for requesting an MCP Server update in Factory 42.
      properties:
        authType:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        endpoint:
          type: string
        name:
          type: string
        transport:
          type: string
      type: object
    models.MCPToolInfo:
      description: Represents a tool exposed by the MCP Server.
      properties:
        description:
          description: What the tool does
          type: string
        inputSchema:
          description: JSON Schema for input
          type: object
        name:
          description: Unique name of the tool
          type: string
        outputSchema:
          description: JSON Schema for output (optional)
          type: object
      type: object
    models.MediaSource:
      description: 'Media content to be displayed by the UI widget of this conversation:'
      properties:
        autoplay:
          description: <video> autoplay
          type: boolean
        headers:
          additionalProperties:
            type: string
          description: Optional HTTP headers for fetching
          type: object
        loop:
          description: <video> loop
          type: boolean
        muted:
          description: <video> muted
          type: boolean
        poster:
          description: Optional poster image for <video>
          type: string
        refreshSec:
          description: 'IMAGE_URL only: >0 enables polling reloads'
          type: integer
        type:
          $ref: '#/components/schemas/models.MediaType'
        url:
          description: Stream or asset URL
          type: string
      type: object
    models.MediaType:
      description: '"HLS" | "DASH" | "MP4" | "MJPEG" | "IMAGE_URL" | "IFRAME"'
      type: string
      x-enum-comments:
        MediaImage: maps to Prisma enum MediaKind.IMAGE_URL
      x-enum-varnames:
      - MediaHLS
      - MediaDASH
      - MediaMP4
      - MediaMJPEG
      - MediaImage
      - MediaIframe
    models.Message:
      description: Represents a single message in a conversation, can be multi-modal.
      properties:
        content:
          description: Array of content parts (multi-modal)
          items:
            $ref: '#/components/schemas/models.OpenAIContentPart'
          type: array
          uniqueItems: false
        conversationId:
          description: Conversation UUID
          type: string
        createdAt:
          description: Timestamp
          type: string
        gatewayId:
          type: string
        id:
          description: Message UUID
          type: string
        metadata:
          type: object
        modelId:
          type: string
        ragCitations:
          description: "\U0001F447 Include the citations generated by RAG in the message
            model:"
          items:
            $ref: '#/components/schemas/models.RAGCitation'
          type: array
          uniqueItems: false
        requestId:
          type: string
        sender:
          description: '"user" | "assistant" | "system"'
          type: string
        senderEmail:
          type: string
        senderName:
          type: string
        tokenCount:
          description: 'Optional: Number of tokens'
          type: integer
      type: object
    models.ModelCapability:
      properties:
        aliases:
          description: alternative Model-IDs/Tags
          items:
            type: string
          type: array
          uniqueItems: false
        id:
          type: string
        modalities:
          items:
            type: string
          type: array
          uniqueItems: false
        tools:
          description: '(25/09/05, 7:51 CEST) - MCP Tool support:'
          properties:
            default_mode:
              description: '"native"|"prompt"'
              type: string
            disable_grammar_when_tools:
              type: boolean
            native:
              description: understands OpenAI-style tools in the payload
              type: boolean
            prompt:
              description: Prompt tools via system message feasible
              type: boolean
            system_template:
              description: optional additional block before tool catalogue
              type: string
          type: object
        vision:
          description: '(25/09/05, 7:53 CEST) - Vision notes for the adapter (Ollama
            & Co.):'
          properties:
            accepts_data_url:
              type: boolean
            accepts_images_array:
              description: 'Ollama: payload.images:[base64]'
              type: boolean
            accepts_url:
              type: boolean
            max_images:
              type: integer
          type: object
      type: object
    models.ModelInfo:
      description: Information about a model served by a Gateway, including framework
        and description.
      properties:
        description:
          description: Human-readable description of the model.
          example: Llama 3 8B v2
          type: string
        framework:
          description: Name of the underlying framework (e.g. LocalAI, Ollama).
          example: Ollama
          type: string
        id:
          description: Unique identifier of the model.
          example: llama-3-8b
          type: string
      type: object
    models.OpenAIContentPart:
      description: Represents a content part in a (multi-modal) chat message (text,
        image, etc).
      properties:
        image_url:
          $ref: '#/components/schemas/models.ImageURL'
        text:
          description: Used if type == "text"
          type: string
        type:
          description: '"text", "image_url", ...'
          type: string
      type: object
    models.RAGCitation:
      description: Represents a cited text chunk from a document.
      properties:
        chunkIndex:
          type: integer
        docId:
          type: string
        docName:
          type: string
        page:
          type: integer
        score:
          type: number
        scoredBy:
          type: string
      type: object
    models.RagProfile:
      description: 'Hierarchical RAG feature flags/config:'
      type: string
      x-enum-varnames:
      - RagProfileFLAT_V1
      - RagProfileHIERARCHICAL_V1
    models.ReceiptItem:
      properties:
        description:
          type: string
        is_discount:
          type: boolean
        line_total_eur:
          type: number
        qty:
          type: number
        unit_price_eur:
          type: number
      type: object
    models.ReceiptRAGProduct:
      properties:
        description:
          type: string
        unit_price_eur:
          type: number
      type: object
    models.ReceiptRAGProducts:
      properties:
        items:
          items:
            $ref: '#/components/schemas/models.ReceiptRAGProduct'
          type: array
          uniqueItems: false
        merchant:
          type: string
      type: object
    models.ReceiptResponse:
      properties:
        currency:
          type: string
        items:
          items:
            $ref: '#/components/schemas/models.ReceiptItem'
          type: array
          uniqueItems: false
        merchant:
          type: string
        rag:
          description: (25/10/30, 18:44 CET) - RAG-friendly minimal products projection
            (optional)
          properties:
            products:
              $ref: '#/components/schemas/models.ReceiptRAGProducts'
          type: object
        raw_text_lines:
          items:
            type: string
          type: array
          uniqueItems: false
        subtotal_eur:
          type: number
        timings:
          $ref: '#/components/schemas/models.ReceiptTimings'
        total_eur:
          type: number
      type: object
    models.ReceiptTimings:
      properties:
        auth_ms:
          description: authentication/authorization
          type: integer
        cluster_ms:
          description: tokens → merged printed lines
          type: integer
        encode_ms:
          description: JSON encode time
          type: integer
        finished_at:
          description: RFC3339Nano in JSON
          type: string
        form_parse_ms:
          description: r.ParseMultipartForm
          type: integer
        ocr_call_ms:
          description: remote OCR POST round-trip
          type: integer
        open_file_ms:
          description: Open() cost before ReadAll
          type: integer
        other_ms:
          description: wall - sum(all measured buckets)
          type: integer
        parse_ms:
          description: printed lines → structured items
          type: integer
        read_upload_ms:
          description: reading multipart+file bytes
          type: integer
        started_at:
          description: RFC3339Nano in JSON
          type: string
        wall_ms:
          description: total from handler entry → response encode
          type: integer
      type: object
    models.UpdateConversationParamsRequest:
      description: Request body of request to update the model parameters in a conversation.
      properties:
        grammar:
          type: string
        max_tokens:
          type: string
        model_settings:
          type: string
        "n":
          type: string
        temperature:
          type: string
        top_k:
          type: string
        top_p:
          type: string
      type: object
    models.User:
      description: Models a Factory 42 user account.
      properties:
        created_at:
          type: string
        email:
          type: string
        id:
          type: string
        name:
          type: string
        oidc_sub:
          type: string
        role:
          $ref: '#/components/schemas/models.UserRole'
        updated_at:
          type: string
      type: object
    models.UserRole:
      type: string
      x-enum-varnames:
      - RoleUser
      - RoleAdmin
      - RoleModerator
    mqttingest.MQTTConfig:
      description: holds connection/session and ingest behavior. All fields map 1:1
        to the JSON kept in ContextSource.Config.
      properties:
        auth:
          properties:
            password:
              type: string
            username:
              type: string
          type: object
        broker:
          description: mqtt:// | mqtts://
          type: string
        clientId:
          type: string
        ingest:
          properties:
            maxInflight:
              description: mapped to MessageChannelDepth
              type: integer
            qosAckTimeoutMs:
              description: subscribe ack wait
              type: integer
            ttlSeconds:
              description: optional TTL for ingested items
              type: integer
          type: object
        session:
          properties:
            autoReconnect:
              type: boolean
            clean:
              type: boolean
            keepAliveSec:
              type: integer
          type: object
        subscriptions:
          items:
            $ref: '#/components/schemas/mqttingest.Subscription'
          type: array
          uniqueItems: false
        tls:
          properties:
            caPEM:
              type: string
            certPEM:
              type: string
            insecureSkipVerify:
              type: boolean
            keyPEM:
              type: string
          type: object
      type: object
    mqttingest.ParserCfg:
      description: Configures how payloads are parsed into ContextItems. All fields
        map 1:1 to the JSON kept in ContextSource.Parser.
      properties:
        deviceIdPath:
          type: string
        messageIdFrom:
          type: string
        metrics:
          additionalProperties:
            type: string
          type: object
        occurredAtPath:
          type: string
        qualityFrom:
          type: string
        sensorIdPath:
          type: string
        seriesKeyTemplate:
          type: string
        tags:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    mqttingest.Subscription:
      description: describes a single MQTT subscription (topic + QoS). RetainHandling
        can be "deliverAtSub" (default) or "noRetained" (client drops retained messages).
      properties:
        qos:
          type: integer
        retainHandling:
          description: '"deliverAtSub" | "noRetained"'
          type: string
        topic:
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key in GUID string format "8D8AC610-566D- ..."
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: JWT in format "Bearer <token string>"
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: ""
  url: ""
info:
  contact:
    name: stulle.ai, München
    url: https://stulle.ai
  description: |-
    REST services of the **Factory 42 API Server**.\
    \
    Last update: 2025-11-20 10:10:43.\
    [Feature flags](https://trunkbaseddevelopment.com/) enabled via Unleash at [https://unleash.stulle.ai/api](https://unleash.stulle.ai/api) (env=[development], app=[factory42-api-dev])
    ```
    │            __        .__  .__                     .__   ©
    │    _______/  |_ __ __|  | |  |   ____      _____  |__|  │
    │   /  ___/\   __\  |  \  | |  | _/ __ \     \__  \ |  |  │
    │   \___ \  |  | |  |  /  |_|  |_\  ___/      / __ \|  |  │
    │  /____  > |__| |____/|____/____/\___  > /\ (____  /__|  │
    │       \/                            \/  \/      \/      │
    ```
    How to run services:
    1. Click **Authorize**.
    2. In the dialog, enter your **API key** under ApiKeyAuth *(header X-API-Key)* and paste your **JWT** under BearerAuth as a Bearer token *(header Authorization: Bearer <token>)*, then authorize both.
    3. Close the dialog.
    4. Choose an endpoint, and click **Try it out**.
    4. Provide any required parameters and hit **Execute** - the request will include both headers.
    5. Check the generated curl to confirm you see ``-H 'X-API-Key: …'`` and ``-H 'Authorization: Bearer …'``.
  license:
    name: MIT License
    url: https://github.com/stulle-ai/factory-42/blob/main/LICENSE
  title: The Factory 42 API for Private AI
  version: 1.4.2
openapi: 3.1.0
paths:
  /v1/audit:
    get:
      description: Returns a paginated list of audit events (optionally filtered).
      parameters:
      - description: 'Maximum number of events to return (default: 25, max: 100)'
        in: query
        name: limit
        schema:
          type: integer
      - description: 'Pagination offset (default: 0)'
        in: query
        name: offset
        schema:
          type: integer
      - description: 'Optional filter: Only events with this action'
        in: query
        name: action
        schema:
          type: string
      - description: 'Optional filter: Only events with this target type'
        in: query
        name: target_type
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.AuditEvent'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List audit trail events
      tags:
      - Audit Trail
    post:
      description: |-
        Record an event as part of the audit trail.
        Possible HTTP status codes:
        • 204: Event recorded
        • 400: Invalid input data (e.g. missing fields)
        • 401: Not authenticated (no or invalid API key/bearer token)
        • 500: Internal server error
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AddAuditEventRequest'
        description: Event attributes
        required: true
      responses:
        "204":
          description: Event successfully recorded
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Invalid input data
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not authenticated
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Record audit event
      tags:
      - Audit Trail
  /v1/context/aggregate:
    get:
      description: In-memory bucketed aggregation over selected items, compatible
        with plain Postgres and TimescaleDB.
      parameters:
      - description: Bucket window, e.g. '5 minutes' or '1 hour'
        in: query
        name: bucket
        required: true
        schema:
          type: string
      - description: Value path, e.g. 'metrics.powerW' or 'payload.value'
        in: query
        name: path
        required: true
        schema:
          type: string
      - description: 'Aggregation fn: avg|min|max|sum|count (default: avg)'
        in: query
        name: fn
        schema:
          type: string
      - description: 'Filter: Source ID'
        in: query
        name: sourceId
        schema:
          type: string
      - description: 'Filter: Conversation ID'
        in: query
        name: conversationId
        schema:
          type: string
      - description: 'Filter: Room ID'
        in: query
        name: roomId
        schema:
          type: string
      - description: 'Filter: Series key'
        in: query
        name: seriesKey
        schema:
          type: string
      - description: 'Filter: Kind'
        in: query
        name: kind
        schema:
          type: string
      - description: 'Filter: From time (RFC3339)'
        in: query
        name: from
        schema:
          type: string
      - description: 'Filter: To time (RFC3339, exclusive)'
        in: query
        name: to
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/managers.Bucket'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Aggregate numeric values over time buckets
      tags:
      - Model Context Aggregation
  /v1/context/items:
    delete:
      description: 'Deletes items using one of: parentId | documentId | batchId |
        sourceId | conversationId | roomId. If only sourceId is given, uses legacy
        DeleteItemsBySource; otherwise uses DeleteItems(DeleteParams).'
      parameters:
      - description: Source ID
        in: query
        name: sourceId
        schema:
          type: string
      - description: Conversation ID
        in: query
        name: conversationId
        schema:
          type: string
      - description: Room ID
        in: query
        name: roomId
        schema:
          type: string
      - description: Parent ID (deletes the parent; children removed via FK CASCADE)
        in: query
        name: parentId
        schema:
          type: string
      - description: Batch ID
        in: query
        name: batchId
        schema:
          type: string
      - description: Document ID
        in: query
        name: documentId
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete items by selector
      tags:
      - Model Context Items
    get:
      description: Lists items with optional filters and ordering.
      parameters:
      - description: Source ID
        in: query
        name: sourceId
        schema:
          type: string
      - description: Conversation ID
        in: query
        name: conversationId
        schema:
          type: string
      - description: Room ID
        in: query
        name: roomId
        schema:
          type: string
      - description: Kind filter
        in: query
        name: kind
        schema:
          type: string
      - description: Series key
        in: query
        name: seriesKey
        schema:
          type: string
      - description: From time (RFC3339)
        in: query
        name: from
        schema:
          type: string
      - description: To time (RFC3339, exclusive)
        in: query
        name: to
        schema:
          type: string
      - description: Limit (default unlimited)
        in: query
        name: limit
        schema:
          type: integer
      - description: Ascending order (default false)
        in: query
        name: asc
        schema:
          type: boolean
      - description: 'Filter: Parent ID (select children of this parent)'
        in: query
        name: parentId
        schema:
          type: string
      - description: 'Filter: Batch ID'
        in: query
        name: batchId
        schema:
          type: string
      - description: 'Filter: Document ID'
        in: query
        name: documentId
        schema:
          type: string
      - description: 'Filter: Tags (CSV or repeated; ANY semantics)'
        in: query
        name: tags
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.ContextItem'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List context items
      tags:
      - Model Context Items
    post:
      description: Adds a single context item. If an idempotency key / dedup hash
        conflicts, insertion is skipped.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.ContextItem'
        description: Context item payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: Skipped due to conflict (idempotent)
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ContextItem'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Add a context item
      tags:
      - Model Context Items
  /v1/context/items/latest:
    get:
      description: Returns the latest N items for a series key.
      parameters:
      - description: Series key
        in: query
        name: seriesKey
        required: true
        schema:
          type: string
      - description: Number of items (default 100)
        in: query
        name: "n"
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.ContextItem'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Latest items by series
      tags:
      - Model Context Items
  /v1/context/items/stream:
    get:
      description: 'Streams new context items as SSE events (event: "item"). Supports
        occurredAt- or createdAt-cursor, optional since, keep-alives, and reconnection
        via Last-Event-ID (RFC3339).'
      parameters:
      - description: Source ID
        in: query
        name: sourceId
        schema:
          type: string
      - description: Conversation ID
        in: query
        name: conversationId
        schema:
          type: string
      - description: Room ID
        in: query
        name: roomId
        schema:
          type: string
      - description: Kind filter
        in: query
        name: kind
        schema:
          type: string
      - description: Series key
        in: query
        name: seriesKey
        schema:
          type: string
      - description: 'Cursor: occurredAt|createdAt (default: occurredAt)'
        in: query
        name: cursor
        schema:
          type: string
      - description: Initial time (RFC3339). If missing, starts at now()
        in: query
        name: since
        schema:
          type: string
      - description: Batch size per poll (default 200, max 1000)
        in: query
        name: pageLimit
        schema:
          type: integer
      - description: Poll interval seconds (default 2, max 60)
        in: query
        name: interval
        schema:
          type: integer
      - description: Keep-alive seconds (default 15)
        in: query
        name: heartbeat
        schema:
          type: integer
      - description: Optional hard connection limit in seconds
        in: query
        name: maxSeconds
        schema:
          type: integer
      - description: 'Filter: Tags (CSV or repeated; ANY semantics)'
        in: query
        name: tags
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
            text/event-stream:
              schema:
                type: string
          description: text/event-stream
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Stream context items using Server-Sent Events (SSE)
      tags:
      - Model Context Items
  /v1/context/items:prune:
    post:
      description: Deletes all items where ttlExpiresAt < now().
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Prune expired items
      tags:
      - Model Context Items
  /v1/context/sources:
    get:
      description: Lists sources filtered by conversationId or roomId (mutually exclusive).
      parameters:
      - description: Conversation ID
        in: query
        name: conversationId
        schema:
          type: string
      - description: Room ID
        in: query
        name: roomId
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.ContextSource'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List context sources
      tags:
      - Model Context Sources
    post:
      description: Creates a new context source under CONVERSATION or ROOM scope.
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: Context source payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ContextSource'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Create context source
      tags:
      - Model Context Sources
  /v1/context/sources/{sourceId}:
    delete:
      description: Deletes a context source by ID (items are dropped via FK CASCADE).
      parameters:
      - description: Source ID
        in: path
        name: sourceId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete context source
      tags:
      - Model Context Sources
    get:
      description: Returns a context source by ID.
      parameters:
      - description: Source ID
        in: path
        name: sourceId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ContextSource'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get context source
      tags:
      - Model Context Sources
  /v1/context/sources/{sourceId}/config:
    patch:
      description: Updates name/config/parser of a context source.
      parameters:
      - description: Source ID
        in: path
        name: sourceId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: Config payload
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Update context source config
      tags:
      - Model Context Sources
  /v1/context/sources/{sourceId}/items:batch:
    post:
      description: Ingests multiple items for a given source, skipping conflicts.
      parameters:
      - description: Source ID
        in: path
        name: sourceId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/models.ContextItem'
              type: array
        description: Items payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: integer
                type: object
          description: inserted/skipped
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Batch ingest context items
      tags:
      - Model Context Items
  /v1/context/sources/{sourceId}/status:
    patch:
      description: Updates status/error/lastIngestAt of a context source.
      parameters:
      - description: Source ID
        in: path
        name: sourceId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: Status payload
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Update context source status
      tags:
      - Model Context Sources
  /v1/conversations:
    get:
      description: Returns all multi-turn conversations of the current user.
      parameters:
      - description: User ID
        in: query
        name: user_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.Conversation'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List all conversations of a user
      tags:
      - Conversations
    post:
      description: Creates a new multi-turn conversation for a user (optionally in
        a knowledge room).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.CreateConversationRequest'
        description: Conversation attributes
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Conversation'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Create a new conversation
      tags:
      - Conversations
  /v1/conversations/{convId}/members/{memberId}:
    delete:
      description: Removes a member from the specified conversation. Only admin/owner
        may remove others.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: User ID
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Remove a member from a conversation
      tags:
      - Conversation Members
  /v1/conversations/{id}:
    delete:
      description: Deletes a conversation and all its messages and participants data
        permanently. No way to recover it!
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
          description: Deleted conversation ID
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete a conversation
      tags:
      - Conversations
    get:
      description: Returns all details of the given conversation (including messages
        and participants).
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Conversation'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get conversation by ID
      tags:
      - Conversations
    patch:
      description: Updates the model parameters of a conversation (e.g. temperature,
        top_k).
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.UpdateConversationParamsRequest'
        description: Model parameters to update
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Conversation'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Update conversation parameters
      tags:
      - Conversations
  /v1/conversations/{id}/assistant:
    post:
      description: Add a model generated message to a conversation. The message is
        broadcasted to all active conversation participants.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AddAssistantMessageRequest'
        description: Assistant message
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Message'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Add an assistant message to a conversation
      tags:
      - Conversation Messages
  /v1/conversations/{id}/join:
    post:
      description: Adds the current user to the specified conversation.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: No Content
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Join a conversation
      tags:
      - Conversation Members
  /v1/conversations/{id}/leave:
    post:
      description: Removes the current user from the specified conversation.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Leave a conversation
      tags:
      - Conversation Members
  /v1/conversations/{id}/members:
    get:
      description: List the members of a conversation running in a knowledge room.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.ConversationParticipant'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List members of a conversation
      tags:
      - Conversation Members
  /v1/conversations/{id}/messages:
    get:
      description: Returns all messages of the conversation in question.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.Message'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List the messages of a conversation
      tags:
      - Conversations
    post:
      description: Adds a (multimodal) message from a user to the given conversation
        and triggers an inference run. The new message is broadcasted to all active
        conversation participants. If there is no @model mention in the text message,
        then no inference is made with the generative model of the conversation.
      parameters:
      - description: Conversation ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AddMessageRequest'
        description: Message to add (multimodal)
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Message'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Add a user message to a conversation
      tags:
      - Conversation Messages
  /v1/gateways:
    get:
      description: Returns a list of all registered Factory 42 Gateway instances.
        Only authenticated users can list gateways. If no gateways are registered,
        an empty array is returned.
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.Gateway'
                type: array
          description: Array of registered gateways (can be empty)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Unauthorized: User is not authenticated'
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal server error or failure querying gateways
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List registered Gateways
      tags:
      - Private AI Gateways
    post:
      description: Registers a new Factory 42 Gateway instance and returns its unique
        identifier. Only authenticated users can register a gateway. The new gateway
        is associated with the calling user and an audit event is logged.
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Gateway successfully registered. The response contains the
            new gateway ID.
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Unauthorized: User is not authenticated'
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal server error or failure registering gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Register a new Gateway
      tags:
      - Private AI Gateways
  /v1/gateways/{id}:
    delete:
      description: Unregisters (deletes) a specific Factory 42 Gateway instance by
        its ID. Only authenticated users can delete gateways. The gateway ID must
        be provided as a URL path parameter. An audit event is logged for the deletion.
      parameters:
      - description: Gateway ID (UUID) to delete
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Gateway successfully unregistered; no content returned
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Unauthorized: User is not authenticated'
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal server error or failure deleting gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Unregister (delete) a Gateway
      tags:
      - Private AI Gateways
  /v1/gateways/models:
    post:
      description: Returns a mapping from model IDs to a list of all currently active
        Factory 42 Gateways which provide the requested model(s). Only authenticated
        users can query the mapping.
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties:
                items:
                  type: string
                type: array
              type: object
        description: 'Request body: { \'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties:
                  items:
                    $ref: '#/components/schemas/models.GatewayModelMapping'
                  type: array
                type: object
          description: Map from model ID to array of gateways
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Bad Request: Malformed request body'
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Unauthorized: User is not authenticated'
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Find active gateways for models
      tags:
      - Private AI Gateways
  /v1/jobs:
    get:
      description: Lists all currently known jobs in the in-memory job store.
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  description: Interface definition of a job running in Factory 42
                    API Server.
                type: array
          description: List of jobs
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List jobs
      tags:
      - Factory 42 Jobs
  /v1/jobs/{jobId}:
    delete:
      description: Deletes a job from the in-memory store. If the job is running,
        this only removes metadata; it does not cancel the underlying work.
      parameters:
      - description: Job ID
        in: path
        name: jobId
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "404":
          content:
            application/json:
              schema:
                type: string
          description: Job not found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete job
      tags:
      - Factory 42 Jobs
    get:
      description: Returns the current status and metadata of a job by ID. Always
        returns JSON. If the job does not exist, a 404 is returned.
      parameters:
      - description: Job ID
        in: path
        name: jobId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                description: Interface definition of a job running in Factory 42 API
                  Server.
          description: Current state of the job
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.JobNotFoundResponse'
          description: Job not found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get job status
      tags:
      - Factory 42 Jobs
  /v1/mcp:
    get:
      description: Returns MCP servers visible to the caller. Filter by roomId or
        conversationId; admins see all.
      parameters:
      - description: Filter by Knowledge Room
        in: query
        name: roomId
        schema:
          type: string
      - description: Filter by Conversation
        in: query
        name: conversationId
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.MCPServer'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List MCP servers
      tags:
      - Model Context Protocol
    post:
      description: Registers a new MCP server for the caller (owner). Secrets are
        set with a separate call.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.MCPServerCreateRequest'
        description: MCP spec
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPServer'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Register MCP server
      tags:
      - Model Context Protocol
  /v1/mcp/{id}:
    delete:
      description: Deletes/unregisters the MCP server. Only the owner or admins may
        perform this action.
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Unregister MCP server
      tags:
      - Model Context Protocol
    get:
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPServer'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Query MCP Server's meta data.
      tags:
      - Model Context Protocol
    patch:
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.MCPServerUpdateRequest'
        description: Patch
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPServer'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Update MCP Server's metadata
      tags:
      - Model Context Protocol
  /v1/mcp/{id}/bindings:
    get:
      description: Returns all bindings (rooms and conversations) for the given MCP
        server.
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.MCPBinding'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get bindings of an MCP server
      tags:
      - Model Context Protocol
    post:
      description: Replaces the bindings of the MCP server with the given set (rooms
        and/or conversations).
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.MCPBindingsUpdateRequest'
        description: Bindings
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.MCPBinding'
                type: array
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Set bindings for an MCP server
      tags:
      - Model Context Protocol
  /v1/mcp/{id}/discover:
    post:
      description: Performs a discovery request (e.g., list tools/prompts/resources)
        against the MCP server.
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPDiscoveryResult'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Discover an MCP Server
      tags:
      - Model Context Protocol
  /v1/mcp/{id}/health:
    get:
      description: |-
        Returns the cached health (lastHealth/lastCheckedAt). With `?force=true` a live probe is executed
        via the manager and the result is persisted best-effort.
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: 'Perform live probe (default: false)'
        in: query
        name: force
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPHealthcheckResult'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get MCP server health
      tags:
      - Model Context Protocol
  /v1/mcp/{id}/healthcheck:
    post:
      description: Probes connectivity and/or performs a lightweight call to assess
        MCP server health.
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPHealthcheckResult'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Healthcheck for an MCP Server
      tags:
      - Model Context Protocol
  /v1/mcp/{id}/tools/call:
    post:
      description: Call a tool implemented by a registered MCP Server (non-streaming).
      parameters:
      - description: MCP Server ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.MCPServerCallToolRequest'
        description: Tool invocation
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPServerCallToolResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Call MCP Server tool
      tags:
      - Model Context Protocol
  /v1/mcp/{id}/tools/refresh:
    post:
      description: |-
        Contacts the MCP server live, fetches the current tool inventory (ToolsList),
        upserts it into the MCPTool table and returns the *live* list in the response.

        Response shape:
        {
        "server_id": "<uuid>",
        "count": 4,
        "tools": [
        { "name": "fs_listDir",  "description": "...", "inputSchema": { ... } },
        { "name": "fs_readText", "description": "...", "inputSchema": { ... } },
        ...
        ]
        }

        Notes:
        - Uses a short server-side timeout (~5s). Persistence errors are logged but do not change 200 responses.
      parameters:
      - description: MCP Server ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.MCPRefreshToolsResponse'
          description: Current tool inventory
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Missing/invalid parameters
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Authentication required
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unexpected server error
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Upstream MCP server not reachable / discovery failed
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Refresh MCP server tools
      tags:
      - Model Context Protocol
  /v1/mcp/{srvId}/bindings/{bndId}:
    delete:
      description: Removes the specific binding from the MCP server.
      parameters:
      - description: MCP Server ID
        in: path
        name: srvId
        required: true
        schema:
          type: string
      - description: Binding ID
        in: path
        name: bndId
        required: true
        schema:
          type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Remove a single MCP Server binding
      tags:
      - Model Context Protocol
  /v1/model-capabilities:
    get:
      description: Returns capabilities for all generative models known by Factory
        42.
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.ModelCapability'
                type: array
          description: List of model capabilities
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: User not authentic
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: No model capabilities available
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List model capabilities
      tags:
      - Model Capabilities
  /v1/model-capabilities/{id}:
    delete:
      description: Deletes capability metadata for a model by its identifier.
      parameters:
      - description: Model identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "204":
          content:
            application/json:
              schema:
                type: string
          description: No Content
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not found or could not delete
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete model capability
      tags:
      - Model Capabilities
    get:
      description: Returns capability metadata for a single model by its identifier.
      parameters:
      - description: Model identifier (e.g., 'gpt-4o-mini')
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ModelCapability'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: User not authentic
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Model capability not found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get model capability
      tags:
      - Model Capabilities
    put:
      description: Creates or updates capability metadata for a model. The `{id}`
        path parameter takes precedence over the body `id` field.
      parameters:
      - description: Model identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.ModelCapability'
        description: Capability payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ModelCapability'
          description: Saved capability
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Invalid JSON
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Persist failed
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Upsert model capability
      tags:
      - Model Capabilities
  /v1/mqtt/connect:
    post:
      description: Uses a stored ContextSource(type=MQTT) to connect the MQTT client.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.MQTTSourceRequest'
        description: Connect payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.MQTTConnectResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Connect an existing MQTT source
      tags:
      - MQ Telemetry Transport
  /v1/mqtt/reconnect:
    post:
      description: Disconnects if connected, then connects again using the stored
        config.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.MQTTSourceRequest'
        description: Reconnect payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.MQTTReconnectResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Reconnect an MQTT source
      tags:
      - MQ Telemetry Transport
  /v1/mqtt/subscribe:
    post:
      description: Creates a ContextSource(type=MQTT) under CONVERSATION or ROOM scope
        and immediately connects it.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.MQTTSubscribeRequest'
        description: Subscribe payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ContextSource'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Subscribe to an MQTT topic (create & connect a source)
      tags:
      - MQ Telemetry Transport
  /v1/mqtt/subscriptions:
    get:
      description: 'Returns ContextSource(type=MQTT) entries that are currently ACTIVE.
        Optional filters: scope and targetId.'
      parameters:
      - description: CONVERSATION or ROOM
        in: query
        name: scope
        schema:
          type: string
      - description: Filter by conversationId (scope=CONVERSATION) or roomId (scope=ROOM)
        in: query
        name: targetId
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.MQTTListActiveResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List active MQTT subscriptions
      tags:
      - MQ Telemetry Transport
  /v1/mqtt/unsubscribe:
    post:
      description: Disconnects an MQTT client by sourceId. Optionally deletes the
        source from DB.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.MQTTSourceRequest'
        description: Unsubscribe payload
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.MQTTUnsubscribeResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Unsubscribe an MQTT source (disconnect)
      tags:
      - MQ Telemetry Transport
  /v1/ready:
    get:
      description: Returns process uptime and health of core dependencies (PostgreSQL,
        Milvus, Unstructured, Feature Flags). This endpoint is public and does not
        require an API key or JWT.
      operationId: get-readiness
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.readyResponse'
          description: All dependencies are healthy
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.readyResponse'
          description: One or more dependencies are degraded or down
      summary: Readiness & dependency health
      tags:
      - Factory 42 API Server Health
  /v1/receipt:
    post:
      description: OCR + structuring of a supermarket receipt (items, totals, discounts,
        merchant).
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: file
        description: Receipt image (JPEG/PNG or single-page PDF)
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ReceiptResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "502":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Gateway
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Parse receipt
      tags:
      - Retail Receipts
  /v1/rooms:
    get:
      description: Returns a list of all Factory 42 knowledge rooms the user has access
        to.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.KnowledgeRoom'
                type: array
          description: OK
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List knowledge rooms
      tags:
      - Knowledge Rooms
    post:
      description: Creates a new Factory 42 knowledge room.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.CreateRoomRequest'
        description: Knowledge room attributes
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.KnowledgeRoom'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Create a knowledge room
      tags:
      - Knowledge Rooms
  /v1/rooms/{roomId}:
    delete:
      description: Deletes a knowledge room by ID. Only accessible by room members.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: OK
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete knowledge room
      tags:
      - Knowledge Rooms
    get:
      description: Returns details for a single knowledge room by ID, enriched with
        vector collection metadata.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.KnowledgeRoomResponse'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get knowledge room
      tags:
      - Knowledge Rooms
  /v1/rooms/{roomId}/conversations:
    get:
      description: Returns all conversations for a given knowledge room.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.Conversation'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List conversations in knowledge room
      tags:
      - Knowledge Room Conversations
    post:
      description: Creates a new conversation in a given knowledge room.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.CreateConversationRequest'
        description: Conversation attributes
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Conversation'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Create conversation in knowledge room
      tags:
      - Knowledge Room Conversations
  /v1/rooms/{roomId}/documents:
    get:
      description: Returns all documents that belong to a knowledge room.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.Document'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List documents in knowledge room
      tags:
      - Knowledge Room Documents
  /v1/rooms/{roomId}/documents/{docId}:
    delete:
      description: Removes an assigned document from a knowledge room (and all associated
        vectors).
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: Created
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Remove document from knowledge room
      tags:
      - Knowledge Room Documents
    post:
      description: Assigns an existing document to a knowledge room.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Add document to knowledge room
      tags:
      - Knowledge Room Documents
  /v1/rooms/{roomId}/documents/{docId}/chunks:
    get:
      description: Returns document/room metadata plus all COMPLETED chunks for the
        document in the given room.
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      - description: Restrict results to this page number (1-based)
        in: query
        name: page
        schema:
          type: integer
      - description: If true (and page is set), return only the best chunk for that
          page based on a heuristic
        in: query
        name: best
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: Metadata and chunk list (optionally filtered)
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List document chunks and embedding metadata in a knowledge room
      tags:
      - Knowledge Room Documents
  /v1/rooms/{roomId}/documents/{docId}/chunks/{chunkIndex}:
    get:
      description: Returns the text content and basic metadata for a single chunk
        (0-based index) of a document inside a knowledge room.
      parameters:
      - description: Room ID (UUID)
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID (UUID)
        in: path
        name: docId
        required: true
        schema:
          type: string
      - description: Chunk index (0-based)
        in: path
        name: chunkIndex
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.GetChunkByIndexResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Missing/invalid parameters
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Access to document denied
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Room, document or chunk not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get chunk content by index
      tags:
      - Knowledge Room Documents
  /v1/rooms/{roomId}/documents/{docId}/embeddings:
    delete:
      description: Removes vector data (Milvus), BM25 index entries, and denormalized
        metadata for the given document in the room. \
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: 'No embeddings existed (fields: message, room_id, document_id,
            embedding_model, hash)'
        "201":
          content:
            application/json:
              schema:
                type: object
          description: 'Deleted (fields: document_id, room_id, finished_at)'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete all embeddings and chunks of a document in a knowledge room
      tags:
      - Knowledge Room Embeddings
    get:
      description: 'Returns one of: \'
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: '`pending` or `none` status payload'
        "201":
          content:
            application/json:
              schema:
                type: object
          description: '`done` status payload'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get embedding status for a document in a room
      tags:
      - Knowledge Room Embeddings
  /v1/rooms/{roomId}/documents/{docId}/query:
    post:
      description: Embeds the query text and searches for the top-K most similar chunks
        within the specified document. \
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: 'Search request (fields: input:string, top_k:int, search_type:enum[L2|IP|COSINE],
          search_mode:enum[embeddings_only|embeddings+bm25], encoding_format:string,
          metadata:object)'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: 'Result payload (fields include: document_name, room_name,
            embedding_model, input, top_k, search_type, numof_chunks, chunks[], elapsed_ms)'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Semantic similarity search within a single document in a knowledge
        room
      tags:
      - Knowledge Room Search
  /v1/rooms/{roomId}/documents/{docId}/vectorize:
    post:
      description: Splits the document into chunks and computes embeddings for each
        chunk using the room's model. \
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: Document ID
        in: path
        name: docId
        required: true
        schema:
          type: string
      - description: 'Process asynchronously (default: false)'
        in: query
        name: async
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: 'No-op: embeddings already exist (fields: message, document_id,
            room_id, embedding_model, hash)'
        "201":
          content:
            application/json:
              schema:
                type: object
          description: 'Sync: vectors created (fields: document_id, room_id, chunks_vectorized,
            embeddings, created_at)'
        "202":
          content:
            application/json:
              schema:
                type: object
          description: 'Async: job accepted (fields: job_id, status_url)'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Vectorize (“embed“) a document in a knowledge room
      tags:
      - Knowledge Room Embeddings
  /v1/rooms/{roomId}/members:
    get:
      description: Returns a list of all users (members) in a knowledge room.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.User'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List users in knowledge room
      tags:
      - Knowledge Room Members
  /v1/rooms/{roomId}/members/{userId}:
    post:
      description: Adds a user as member to a knowledge room.
      parameters:
      - description: Room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      - description: User ID
        in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AddUserToRoomRequest'
        description: User role
        required: true
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Add user to knowledge room
      tags:
      - Knowledge Room Members
  /v1/rooms/{roomId}/query:
    post:
      description: Embeds the query text and searches for the top-K most similar chunks
        across all documents in the room. \
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: 'Search request (fields: input:string, top_k:int, search_type:enum[L2|IP|COSINE],
          search_mode:enum[embeddings_only|embeddings+bm25], search_range:enum[documents|conversations|all],
          encoding_format:string, metadata:object)'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: 'Result payload (fields include: room_name, embedding_model,
            input, top_k, search_type, numof_chunks, chunks[], elapsed_ms)'
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Semantic similarity search across an entire knowledge room
      tags:
      - Knowledge Room Search
  /v1/rooms/{roomId}/vectorize:
    post:
      description: Computes an embedding for a short input text using the room's configured
        embedding model. \
      parameters:
      - description: Knowledge room ID
        in: path
        name: roomId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.CreateEmbeddingRequest'
        description: Embedding request payload
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.EmbeddingResponse'
          description: Embedding successfully created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Invalid input or room
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Room not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal error while computing or persisting
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Create an ad-hoc embedding in a knowledge room
      tags:
      - Knowledge Room Embeddings
  /v1/users:
    get:
      description: Returns all registered Factory 42 users. Only accessible to Factory
        42 admins.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/models.User'
                type: array
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Forbidden: Admins only'
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Failed to list users
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: List all users
      tags:
      - Factory 42 Users
    post:
      description: |-
        Creates a Factory 42 user account. Only accessible to Factory 42 admins. In addition to the Facory 42 user account, the user needs an account with the identity provider (IdP), which is currently authentik.
        Possible HTTP status codes:
        • 200: User successfully created
        • 400: Invalid input data (e.g. missing fields)
        • 401: Not authenticated (no or invalid API key/bearer token)
        • 403: Forbidden (caller is authenticated, but not admin)
        • 409: Conflict (date of new user is not unique)
        • 500: Internal server error
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.CreateUserRequest'
        description: User attributes
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.User'
          description: User successfully created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Invalid input data
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Not authenticated
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Forbidden
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Conflict
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Create user account
      tags:
      - Factory 42 Users
  /v1/users/{id}:
    delete:
      description: Deletes a Factory 42 user account by ID. Only accessible to Factory
        42 admins. Please don't forget to delete the user in the IdP as well.
      parameters:
      - description: Factory 42 User ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.User'
          description: User successfully deleted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: 'Forbidden: Admins only'
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: User not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: Failed to delete user
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Delete a user
      tags:
      - Factory 42 Users
  /v1/users/me:
    get:
      description: Returns the currently authenticated Factory 42 user.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.User'
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
          description: User not found or unauthorized
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: Get current user
      tags:
      - Factory 42 Users
