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

# References (v2)

> Retrieves the list of evidence references (citations) used in a conversation.

The [Analytics SSE](/api-reference/basic/analytics-sse) endpoint streams the generated answer but **does not include references in the response**. Use this endpoint after the stream completes to fetch the full list of references that were cited in the answer.

**Usage Flow:**
1. Call the Analytics SSE endpoint (`POST /v1/analytics/sse`)
2. From the SSE stream, find the `conversation` event → extract `conversation_id`
3. After the stream finishes, call this endpoint with the `conversation_id`
4. The response contains all references with citation index, source document info, and metadata

**How to view original documents:**
- **Via Viewer:** `https://chat.linqalpha.com/rms/viewer?conversation_id={conversation_id}&citation_idx={citation_idx}`



## OpenAPI

````yaml GET /v2/conversations/{conversation_id}/references
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/conversations/{conversation_id}/references:
    get:
      tags:
        - Data
      summary: References (v2)
      description: >-
        Retrieves the list of evidence references (citations) used in a
        conversation.


        The [Analytics SSE](/api-reference/basic/analytics-sse) endpoint streams
        the generated answer but **does not include references in the
        response**. Use this endpoint after the stream completes to fetch the
        full list of references that were cited in the answer.


        **Usage Flow:**

        1. Call the Analytics SSE endpoint (`POST /v1/analytics/sse`)

        2. From the SSE stream, find the `conversation` event → extract
        `conversation_id`

        3. After the stream finishes, call this endpoint with the
        `conversation_id`

        4. The response contains all references with citation index, source
        document info, and metadata


        **How to view original documents:**

        - **Via Viewer:**
        `https://chat.linqalpha.com/rms/viewer?conversation_id={conversation_id}&citation_idx={citation_idx}`
      parameters:
        - name: conversation_id
          in: path
          description: Conversation ID (UUID). Provided in the `conversation` SSE event.
          required: true
          schema:
            type: string
            format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        - name: organization_id
          in: query
          description: >-
            Organization ID. Required for platform API keys to identify the
            target organization.
          required: false
          schema:
            type: string
            format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        - name: user_id
          in: query
          description: >-
            User ID. Required together with `user_email` for platform API keys
            to identify the specific user who owns the conversation.
          required: false
          schema:
            type: string
          example: user-123
        - name: user_email
          in: query
          description: >-
            User email. Required together with `user_id` for platform API keys
            to identify the specific user who owns the conversation.
          required: false
          schema:
            type: string
            format: email
          example: john.doe@example.com
      responses:
        '200':
          description: References response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferencesV2Response'
              example:
                error: null
                payload:
                  references:
                    - id: 9162ee3d-e71e-4f2d-81a7-9981ecb06597
                      citation_idx: 1
                      search_type: rms
                      chunk_id: '7601005986849213491'
                      text: >-
                        Through our Apple Manufacturing Academy in Detroit,
                        we're already training American businesses and
                        innovators on the latest smart manufacturing and
                        artificial intelligence techniques. Six months since
                        opening, the academy is already making an enormously
                        positive impact...
                      text_type: paragraph
                      document_id: ed6ed077-949c-46ec-b036-d01fafc9bb84
                      document_name: Apple, Inc., Q1 2026 Earnings Call, 29-January-2026 5
                      s3_file_key: null
                      external_url: ''
                      metadata:
                        rms_type: null
                        rms_sub_type: null
                        rms_document_type: earnings_call
                        source: null
                        countries: null
                        regions: null
                        participants: null
                        tags: null
                        publisher: null
                        calendar_date: null
                        fiscal_year: null
                        fiscal_quarter: null
                        document_category: earnings_call
                        document_subcategory: null
                        sector: null
                        subsector: null
                        stock_ids:
                          - BBG001S5N8V8
                        tickers:
                          - AAPL
                        company_names: null
                        offset: null
                        snippet: null
                    - id: 05cc6e75-674c-4263-9427-a2113d06a51c
                      citation_idx: 2
                      search_type: rms
                      chunk_id: '7575071132181705859'
                      text: >-
                        Our revenue of $102.5 billion was up 8% year-over-year
                        and is a new September quarter record. We set September
                        quarter records in the Americas, Europe, Japan and the
                        rest of Asia Pacific, and grew in the vast majority of
                        markets we track...
                      text_type: paragraph
                      document_id: c893ee34-fb85-491d-b667-0be2be515418
                      document_name: Apple, Inc., Q4 2025 Earnings Call, 30-October-2025 5
                      s3_file_key: null
                      external_url: ''
                      metadata:
                        rms_type: null
                        rms_sub_type: null
                        rms_document_type: earnings_call
                        source: null
                        countries: null
                        regions: null
                        participants: null
                        tags: null
                        publisher: null
                        calendar_date: null
                        fiscal_year: null
                        fiscal_quarter: null
                        document_category: earnings_call
                        document_subcategory: null
                        sector: null
                        subsector: null
                        stock_ids:
                          - BBG001S5N8V8
                        tickers:
                          - AAPL
                        company_names: null
                        offset: null
                        snippet: null
        '400':
          description: Bad Request - Invalid conversation_id format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST_BODY
                  msg: conversation_id must be a valid UUID
                  message: conversation_id must be a valid UUID
                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
components:
  schemas:
    ReferencesV2Response:
      type: object
      properties:
        references:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceV2'
          description: List of references associated with the conversation
      required:
        - references
    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
    ReferenceV2:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Reference ID
        citation_idx:
          type: integer
          description: Citation index number
        search_type:
          type: string
          description: Type of search that produced this reference (e.g., "rms")
        chunk_id:
          type: string
          description: Chunk identifier
        text:
          type: string
          description: Reference text content
        text_type:
          type: string
          description: Type of text (e.g., "paragraph")
        document_id:
          type: string
          format: uuid
          description: Document ID. Use with presigned_url endpoint for direct download.
        document_name:
          type: string
          description: Document name
        s3_file_key:
          type: string
          nullable: true
          description: S3 file key (may be null)
        external_url:
          type: string
          description: External URL for the document
        metadata:
          $ref: '#/components/schemas/ReferenceMetadataV2'
      required:
        - id
        - citation_idx
        - search_type
        - chunk_id
        - text
        - text_type
        - document_id
        - document_name
        - s3_file_key
        - external_url
        - metadata
    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
    ReferenceMetadataV2:
      type: object
      properties:
        rms_type:
          type: string
          nullable: true
        rms_sub_type:
          type: string
          nullable: true
        rms_document_type:
          type: string
          nullable: true
          description: Document type (e.g., "earnings_call", "filing")
        source:
          type: string
          nullable: true
        countries:
          type: array
          items:
            type: string
          nullable: true
        regions:
          type: array
          items:
            type: string
          nullable: true
        participants:
          type: array
          items:
            type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        publisher:
          type: string
          nullable: true
        calendar_date:
          type: string
          nullable: true
        fiscal_year:
          type: string
          nullable: true
        fiscal_quarter:
          type: string
          nullable: true
        document_category:
          type: string
          nullable: true
          description: Document category (e.g., "earnings_call")
        document_subcategory:
          type: string
          nullable: true
        sector:
          type: string
          nullable: true
        subsector:
          type: string
          nullable: true
        stock_ids:
          type: array
          items:
            type: string
          nullable: true
          description: Bloomberg Global Identifiers (e.g., ["BBG001S5N8V8"])
        tickers:
          type: array
          items:
            type: string
          nullable: true
          description: Ticker symbols (e.g., ["AAPL"])
        company_names:
          type: array
          items:
            type: string
          nullable: true
        offset:
          type: integer
          nullable: true
        snippet:
          type: string
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````