> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linqalpha.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> Generate a response from the LinqAlpha engine. LinqAlpha uses different types of language models and data sources to generate an answer. The response is provided as a server-sent events (SSE) stream.

**Note**: For this search chat endpoint, the stock_id (BBG_ID) can be obtained by referring to the [Map Tickers API](https://docs.linqalpha.com/api-reference/basic/map_tickers) and using the `stock_id` value from its response.



## OpenAPI

````yaml POST /v2/chat/sse
openapi: 3.0.1
info:
  title: LinqAlpha API
  description: >-
    Linq helps finance professionals make informed decisions using
    Retrieval-Augmented Generation (RAG)-enhanced answers. By leveraging
    cutting-edge Large Language Models (LLM) and supplementary technology, Linq
    provides the most optimized responses based on your queries.
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://api.linqalpha.com
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: Search and generate responses
  - name: Data
    description: Data retrieval and mapping
  - name: Feedback
    description: Conversation feedback
  - name: RMS
    description: Research Management System
  - name: Source Management
    description: Source batch and file management
  - name: MCP
    description: >-
      LinqAlpha MCP — Financial data tools for AI assistants via Model Context
      Protocol
  - name: Connectors
    description: Customer Connectors — customer-owned MCP connector management
  - name: Briefing
    description: Briefing Agent — automated market briefings with scheduling and delivery
  - name: Status
    description: Sync status — check organization, document, and container sync progress
paths:
  /v2/chat/sse:
    post:
      tags:
        - Search
      summary: Generate a response from the LinqAlpha engine via SSE
      description: >-
        Generate a response from the LinqAlpha engine. LinqAlpha uses different
        types of language models and data sources to generate an answer. The
        response is provided as a server-sent events (SSE) stream.


        **Note**: For this search chat endpoint, the stock_id (BBG_ID) can be
        obtained by referring to the [Map Tickers
        API](https://docs.linqalpha.com/api-reference/basic/map_tickers) and
        using the `stock_id` value from its response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatSseV2Request'
            example:
              query: What are the latest insights on AAPL performance?
              stock_ids:
                - BBG001S5N8V8
              tickers:
                - AAPL
              external_types:
                - transcript
                - filing
                - news
                - ir_slide
      responses:
        '200':
          description: SSE stream response with RMS search results
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ConversationEvent'
                  - $ref: '#/components/schemas/ThinkEvent'
                  - $ref: '#/components/schemas/SubQuestionsEvent'
                  - $ref: '#/components/schemas/StatusEvent'
                  - $ref: '#/components/schemas/DialogueIdEvent'
                  - $ref: '#/components/schemas/SearchResultsEvent'
                  - $ref: '#/components/schemas/AnswerEvent'
                discriminator:
                  propertyName: event_name
                  mapping:
                    conversation:
                      $ref: '#/components/schemas/ConversationEvent'
                    think:
                      $ref: '#/components/schemas/ThinkEvent'
                    sub_questions:
                      $ref: '#/components/schemas/SubQuestionsEvent'
                    status:
                      $ref: '#/components/schemas/StatusEvent'
                    dialogue_id:
                      $ref: '#/components/schemas/DialogueIdEvent'
                    search_results:
                      $ref: '#/components/schemas/SearchResultsEvent'
                    answer:
                      $ref: '#/components/schemas/AnswerEvent'
              examples:
                conversation_created:
                  summary: 2. Conversation Created Event
                  description: Conversation creation event - first event in the stream
                  value:
                    event_name: conversation
                    data:
                      conversation_id: 123e4567-e89b-12d3-a456-426614174000
                think_event:
                  summary: 3. Think Event
                  description: Streamed reasoning/planning process
                  value:
                    event_name: think
                    data:
                      think_piece: <PLAN_REASONING>
                sub_questions_event:
                  summary: 4. Sub Questions Event
                  description: Sub-questions generated for the current message
                  value:
                    event_name: sub_questions
                    data:
                      sub_questions:
                        - >-
                          What is the latest news about JP morgan equity
                          research asia?
                        - >-
                          What is the latest news about JP morgan equity
                          research asia?
                status_event:
                  summary: 5. Status Event - Finish
                  description: Indicates stream has completed
                  value:
                    event_name: status
                    data:
                      status: finish
                dialogue_id_event:
                  summary: 6. Dialogue ID Event
                  description: Unique identifier for the current dialogue
                  value:
                    event_name: dialogue_id
                    data:
                      dialogue_id: 123e4567-e89b-12d3-a456-426614174000
                search_results_event:
                  summary: 7. Search Results ID Event
                  description: Unique identifier for the search results
                  value:
                    event_name: search_results
                    data:
                      chat_message_id: 123e4567-e89b-12d3-a456-426614174000
                answer_event:
                  summary: 8. Answer Event
                  description: Streamed answer content
                  value:
                    event_name: answer
                    data:
                      answer_piece: Based on the latest research...
        '400':
          description: Bad Request - Invalid request parameters or incorrect format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              examples:
                invalid_upload_period:
                  summary: Invalid upload_period format
                  value:
                    error:
                      code: INVALID_REQUEST_BODY
                      message: >-
                        upload_period.start_time must be an object with year
                        (integer), month (integer 1-12), and optional day
                        (integer 1-31). Example: {"year": 2025, "month": 1,
                        "day": 1}
                    payload: null
                missing_query:
                  summary: Missing required field
                  value:
                    error:
                      code: INVALID_REQUEST_BODY
                      message: query is required and must be a string
                    payload: null
        '401':
          description: Unauthorized - Invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: API_KEY_MISSING
                  msg: header does not contain api key
                  message: header does not contain api key
                payload: null
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: SERVER_ERROR
                  message: An unexpected error occurred on the server.
                payload: null
components:
  schemas:
    ChatSseV2Request:
      type: object
      properties:
        query:
          type: string
          description: A search query
          example: What are the latest updates on AAPL?
        conversation_id:
          type: string
          format: uuid
          description: >-
            Conversation id (optional)


            Every user-initiated chat is grouped under a conversation. A
            conversation contains one or more messages generated either by the
            user or LinqAlpha. Use the conversation_id to track the context of
            previous interactions.
          example: 123e4567-e89b-12d3-a456-426614174000
        stock_ids:
          type: array
          items:
            type: string
          description: Bloomberg stock IDs (optional)
          example:
            - BBG001S5N8V8
        tickers:
          type: array
          items:
            type: string
          description: Ticker symbols (optional)
          example:
            - AAPL
        external_types:
          type: array
          items:
            type: string
          description: >-
            External document types (optional, defaults to ["transcript",
            "filing", "news", "ir_slide"])
          default:
            - transcript
            - filing
            - news
            - ir_slide
          example:
            - transcript
            - filing
            - news
            - ir_slide
        top_k:
          type: number
          description: >-
            Specifies the number of top search results to return.

            If the value exceeds 50, it will be capped at 50

            The number of returned results will be less than or equal to the
            specified top_k value.

            Results are sorted by relevancy in descending order (from highest to
            lowest).
          example: 50
        upload_period:
          type: object
          description: >-
            Filter documents by upload date range. At least one of start_time or
            end_time must be provided.
          properties:
            start_time:
              $ref: '#/components/schemas/DateFilter'
            end_time:
              $ref: '#/components/schemas/DateFilter'
          example:
            start_time:
              year: 2025
              month: 1
              day: 1
            end_time:
              year: 2026
              month: 1
              day: 17
      required:
        - query
    ConversationEvent:
      description: Conversation event
      allOf:
        - $ref: '#/components/schemas/ChatSseEvent'
        - properties:
            event_name:
              enum:
                - conversation
            data:
              type: object
              required:
                - conversation_id
              properties:
                conversation_id:
                  type: string
                  description: >-
                    Unique conversation identifier. Use for multi-turn
                    continuation and References API.
                message:
                  type: string
                  description: >-
                    Status message (e.g., 'Successfully created a
                    conversation.')
              description: Event-specific data payload
    ThinkEvent:
      description: Thinking/reasoning process stream
      allOf:
        - $ref: '#/components/schemas/BaseSseEvent'
        - properties:
            event_name:
              enum:
                - think
            data:
              type: object
              required:
                - think_piece
              properties:
                think_piece:
                  type: string
                  description: >-
                    A piece of the thinking/reasoning process (streamed
                    incrementally)
                  example: <PLAN_REASONING>
    SubQuestionsEvent:
      description: Sub-questions event
      allOf:
        - $ref: '#/components/schemas/BaseSseEvent'
        - properties:
            event_name:
              enum:
                - sub_questions
            data:
              type: object
              required:
                - sub_questions
              properties:
                sub_questions:
                  type: array
                  description: Sub-questions
                  items:
                    type: string
                    description: Sub-question
    StatusEvent:
      description: Stream status event (start/finish)
      allOf:
        - $ref: '#/components/schemas/BaseSseEvent'
        - properties:
            event_name:
              enum:
                - status
            data:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum:
                    - start
                    - finish
                  description: Stream status indicator
    DialogueIdEvent:
      type: object
      description: Dialogue id streaming event
      allOf:
        - $ref: '#/components/schemas/ChatSseEvent'
        - properties:
            event_name:
              enum:
                - dialogue_id
            data:
              type: object
              required:
                - dialogue_id
              properties:
                dialogue_id:
                  type: string
                  description: >-
                    A unique identifier (UUID) that represents a specific
                    dialogue or message exchange within a chat session. This ID
                    is provided as an event during the chat process, appearing
                    in the stream before any think events.


                    The dialogue_id serves to uniquely identify individual
                    dialogue instances within a chat session, enabling precise
                    control over message streaming and interruption. Here, a
                    dialogue is defined as a single question and answer pair -
                    so a single chat_session is composed of a sequence of
                    dialogues.


                    Unlike using only the chat_session_id, the dialogue_id
                    prevents race conditions that could occur when multiple
                    windows or instances interact with the same chat session
                    simultaneously. 
    SearchResultsEvent:
      description: Search result id streaming event
      allOf:
        - $ref: '#/components/schemas/ChatSseEvent'
        - properties:
            event_name:
              enum:
                - search_results
            data:
              type: object
              required:
                - chat_message_id
              properties:
                chat_message_id:
                  type: string
                  description: >-
                    Chat message id (You can retrieve search_results using the
                    chat_message_id through the references API.)
    AnswerEvent:
      description: Final answer streaming event
      allOf:
        - $ref: '#/components/schemas/BaseSseEvent'
        - properties:
            event_name:
              enum:
                - answer
            data:
              type: object
              required:
                - answer_piece
              properties:
                answer_piece:
                  type: string
                  description: >-
                    A piece of the final answer (streamed incrementally).
                    Citations are embedded as [hash] format.
                  example: '### Executive Summary'
    ApiErrorResponse:
      type: object
      description: Standard error response wrapper
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
        payload:
          description: Always null for error responses
          nullable: true
      required:
        - error
        - payload
    DateFilter:
      type: object
      description: Date filter with year, month, and optional day
      properties:
        year:
          type: integer
          description: Year (e.g., 2025)
          example: 2025
        month:
          type: integer
          description: Month (1-12)
          minimum: 1
          maximum: 12
          example: 1
        day:
          type: integer
          description: Day of month (1-31, optional)
          minimum: 1
          maximum: 31
          example: 15
      required:
        - year
        - month
    ChatSseEvent:
      type: object
      description: Base structure for all Chat SSE events
      required:
        - event_name
        - data
      properties:
        event_name:
          type: string
          enum:
            - conversation
            - status
            - think
            - sub_questions
            - dialogue_id
            - search_results
            - answer
        data:
          type: object
          description: Event-specific data payload
    BaseSseEvent:
      type: object
      description: Base structure for SSE events
      required:
        - event_name
        - data
      properties:
        event_name:
          type: string
          enum:
            - status
            - research_progress
            - round
            - think
            - sub_questions
            - tool_call
            - tool_response
            - search_results
            - answer
          description: Type of SSE event
        data:
          type: object
          description: Event-specific data payload
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: >-
            Error code indicating the type of error. Common codes:

            - Authentication: `API_KEY_MISSING`, `INVALID_API_KEY`

            - Validation: `INVALID_REQUEST_BODY`, `ORGANIZATION_ID_MISSING`,
            `TICKERS_MISSING`, `CHAT_MESSAGE_ID_MISSING`, `DOCUMENT_ID_MISSING`

            - Service: `SEARCH_FAIL`, `TTS_FAIL`, `CREATE_CONV_FAIL`,
            `GET_STOCK_FAIL`, `CREATE_MSG_FAIL`, `ALPHA_COMP_FAIL`,
            `GET_REF_FAIL`

            - Connectors: `CONNECTOR_LIST_FAIL`, `CONNECTOR_NOT_FOUND`,
            `CONNECTOR_CREATE_FAIL`, `CONNECTOR_UPDATE_FAIL`,
            `CONNECTOR_DELETE_FAIL`, `CONNECTOR_TEST_FAIL`

            - Not Found: `NOT_FOUND`
          example: INVALID_REQUEST_BODY
        msg:
          type: string
          description: Error message (deprecated, use `message` instead)
          example: query is required and must be a string
        message:
          type: string
          description: Error message providing more details about the error
          example: query is required and must be a string
      required:
        - code
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````