LinqAlpha Data API

openapi: 3.0.1
info:
  title: LinqAlpha Briefing Data 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: Data
  description: Data retrieval and mapping
paths:
  /v1/chat_messages/{chat_message_id}:
    get:
      summary: Chat Message
      description: 'Retrieves a specific chat message by its ID.


        **How to find chat_message_id:**

        Look for the event with `event_name` set to `search_results` in the Chat API response data. For detailed instructions, see [search_results event response](https://docs.linqalpha.com/api-reference/basic/chat_v2#option-6).'
      parameters:
      - name: chat_message_id
        in: path
        description: Chat message ID
        required: true
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Chat message response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessageResponse'
              example:
                chat_message_id: 123e4567-e89b-12d3-a456-426614174000
                message: The company's revenue grew by 20% in the last quarter. ...
                message_type: assistant
                created_at: '2025-10-30T09:11:31.667544Z'
        '400':
          description: Bad Request - Missing or invalid chat_message_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: CHAT_MESSAGE_ID_MISSING
                  msg: chat_message_id is required
                  message: chat_message_id is required
                payload: null
        '401':
          description: Unauthorized - Invalid API key or 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
      tags:
      - Data
  /v1/references:
    get:
      summary: References
      description: 'Retrieves evidence references for a specific chat message. Each reference corresponds to an exact chunk used in the final answer generated by the LinqAlpha engine. These chunks represent the precise portions of documents (e.g., filings, transcripts, or news) that were retrieved and cited by the model to construct the final response..


        **How to find chat_message_id:**

        Look for the event with `event_name` set to `search_results` in the Chat API response data. For detailed instructions, see [search_results event response](https://docs.linqalpha.com/api-reference/basic/chat_v2#option-6).


        **How to view original documents:**

        1. **Via Viewer:** `https://chat.linqalpha.com/rms/viewer?chat_message_id={chat_message_id}&citation_idx={citation_idx}`

        2. **Direct Download:** If the reference contains a `document_id`, you can access the original document directly through the [presigned_url endpoint](https://docs.linqalpha.com/api-reference/basic/presigned_url).'
      parameters:
      - name: chat_message_id
        in: query
        description: Chat message ID
        required: true
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: References response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferencesResponse'
              example:
                references:
                - id: '12'
                  citation_idx: '12'
                  search_type: rms
                  chunk_id: 123e4567-e89b-12d3-a456-426614174000
                  text: For fiscal year 2024, Tesla expects EBIT to grow between 15% and 20%...
                  text_type: paragraph
                  document_id: 123e4567-e89b-12d3-a456-426614174000
                  document_name: Tesla 10-K 2023
                  s3_file_key: tesla/filings/2023/10k.pdf
                  external_url: https://www.sec.gov/ix?doc=/Archives/edgar/data/1318605/000095017024002308/tsla-20231231.htm
                  metadata:
                    source: filing
                    ticker: TSLA
                    published_at: '2024-02-14'
                  custom_metadata: null
        '400':
          description: Bad Request - Invalid request parameters or incorrect format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: CHAT_MESSAGE_ID_MISSING
                  msg: chat_message_id is required
                  message: chat_message_id is required
                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
        '403':
          description: Forbidden - No permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: 'Access denied: insufficient permissions.'
                payload: null
        '404':
          description: Not Found - The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                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
      tags:
      - Data
  /v2/conversations/{conversation_id}/references:
    get:
      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
      tags:
      - Data
  /v2/analytics/conversations/{conversation_id}/references:
    get:
      summary: Analytics V2 References
      description: 'Retrieves the list of evidence references (citations) used in an analytics conversation, in normalized format with enriched metadata.


        > **Note:** This endpoint returns references from the Analytics V2 SSE endpoint. Some source types (e.g., `rms`) require a separate onboarding process. For more information, please contact us at support@linqalpha.com.


        **Usage Flow:**

        1. Call the Analytics SSE V2 endpoint (`POST /v2/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}`


        **Note:** This endpoint returns references in the same normalized format as the v1 references API, with enriched metadata fields (s3_file_key, external_url, calendar_date, fiscal_year, etc.). Use this endpoint when consuming the v2 analytics SSE stream.'
      parameters:
      - name: conversation_id
        in: path
        description: Conversation ID (UUID). Provided in the `conversation` SSE event from the Analytics SSE V2 endpoint.
        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 (normalized format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsReferencesResponse'
              example:
                error: null
                payload:
                  references:
                  - id: '1'
                    citation_idx: '1'
                    search_type: rms
                    chunk_id: ad477254-58ef-4965-b86a-26ff9f5b3614
                    text: UBS Investment Research report on energy sector companies...
                    text_type: paragraph
                    document_id: 47061a59-2e02-4711-a096-8ba5744c73d0
                    document_name: ued39062.pdf
                    s3_file_key: production/data-original/1ec8b21f-c799-4fbb-a6cc-1548d45334f3/organization/2a96a7ca-f2ba-4098-92f8-742e9eb2ede6/s3/4b24a452b612b89d2c046e1740c5c6f75952ce8abc46b00abcc548409196f9f3.pdf
                    external_url: null
                    metadata:
                      calendar_date: '2026-03-02T00:00:00Z'
                      fiscal_year: 2025
                      fiscal_quarter: 4
                      source: filing
                      tickers:
                      - BRKM5
                      - ECOPETL
                      - PETR4
                      - YPFD
                      - PRIO3
                      company_names:
                      - Braskem
                      - Ecopetrol
                      - Petrobras
                      - YPF
                      - PRIO
                      stock_ids:
                      - BBG001S6ZH89
                      - BBG001SSJG36
                      - BBG001S7GRB2
                      - BBG001S7KCP5
                      - BBG001T9LDJ4
                      document_category: Analysis, Report & Note
                      document_subcategory: Brokerage
                      rms_document_type: null
                      rms_type: null
                      rms_sub_type: null
                      sector:
                      - Energy
                      subsector:
                      - Oil & gas
                      publisher: UBS
                      countries:
                      - United States
                      - Iran
                      - Israel
                      - Saudi Arabia
                      - Brazil
                      regions:
                      - North America
                      - EMEA
                      - LatAm
                      - Europe
                      - APAC
                      participants:
                      - name: Donald Trump
                        role: President
                        organization: United States
                        participation_type: referenced
                      tags: []
                      parent_id: 608fabf4-c879-486f-83d1-3a889d91f74e
                      parent_document_id: 608fabf4-c879-486f-83d1-3a889d91f74e
                      creation_timestamp: '2026-03-02T15:49:29+00:00'
                      last_contribution_timestamp: '2026-03-02T15:49:29+00:00'
                      document_tags:
                      - research_report
                      - brokerage
                      creator_name: null
                      last_contributor_name: null
                      offset:
                      - top: 0.683
                        left: 0.076
                        page: 8
                        width: 0.561
                        height: 0.229
                    custom_metadata: 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
      tags:
      - Data
  /v1/ttsql:
    post:
      summary: TTSQL
      description: Converts natural language query to SQL, executes it, and returns results in markdown format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsRequest'
            example:
              query: Show me NVIDIA's quarterly revenue and net income for 2024
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtsResponse'
              example:
                code: 0
                success: true
                message: success
                response:
                  execution_id: 2548d578-0446-4abc-b6f6-f50c966d341c
                  stock_name_mapping:
                    BBG001S5TZJ6: NVIDIA Corporation
                  currency_info:
                  - currency: USD
                    exchange_rate: 1
                  field_currency_info:
                    BBG001S6Q004:
                      SALES: TWD
                      EPS: TWD
                      ff_sales: TWD
                  execution_duration: 171
                  date_range:
                  - '2024-01-01'
                  - '2024-12-31'
                  rdb_result: '### Company Annual Financials


                    | name | Fiscal Period End Date | Dividends Per Share |

                    | --- | --- | --- |

                    | NVIDIA Corporation | 2024-01-31 | 0.016 |'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized - Invalid API key or 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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Data
  /v1/map_tickers:
    get:
      summary: Map tickers to stock IDs
      description: Accepts a list of ticker strings via query parameters and returns their corresponding stock IDs (BBG IDs).
      parameters:
      - name: tickers
        in: query
        description: One or more ticker symbols to map. Can be repeated multiple times, e.g., `tickers=AAPL&tickers=GOOG`.
        required: true
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example: tickers=AAPL&tickers=GOOG&tickers=MSFT&tickers=AMZN&tickers=TSLA&tickers=NVDA&tickers=META&tickers=NFLX&tickers=TSM&tickers=WMT
      responses:
        '200':
          description: Mapping results of tickers to stock IDs
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    nullable: true
                  payload:
                    type: array
                    items:
                      type: object
                      properties:
                        raw_ticker:
                          type: string
                        stock_id:
                          type: string
              example:
                error: null
                payload:
                - raw_ticker: AAPL
                  stock_id: BBG001S5N8V8
                - raw_ticker: GOOGL
                  stock_id: BBG009S39JY5
                - raw_ticker: MSFT
                  stock_id: BBG001S5TD05
                - raw_ticker: AMZN
                  stock_id: BBG001S5PQL7
                - raw_ticker: TSLA
                  stock_id: BBG001SQKGD7
                - raw_ticker: NVDA
                  stock_id: BBG001S5TZJ6
                - raw_ticker: META
                  stock_id: BBG001SQCQC5
        '400':
          description: Bad Request - if the provided ticker list is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: TICKERS_MISSING
                  msg: tickers query parameter is required
                  message: tickers query parameter is required
                payload: null
        '401':
          description: Unauthorized - Invalid API key or 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 - if 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
      tags:
      - Data
  /v1/documents/{document_id}/presigned_url:
    get:
      summary: Presigned URL
      description: 'Generates a temporary presigned URL for secure access to the original document file.


        Provide a `document_id` (obtained from the References API) to receive a time-limited (10 min) URL that allows you to download or view the source document directly. This is useful when you need to access the actual file that was referenced in the search results.'
      parameters:
      - name: document_id
        in: path
        description: Document ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Presigned URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: Presigned URL
        '400':
          description: Bad Request - Missing or invalid document_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: DOCUMENT_ID_MISSING
                  msg: document_id is required
                  message: document_id is required
                payload: null
        '401':
          description: Unauthorized - Invalid API key or 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
      tags:
      - Data
  /v1/documents/batch_presigned_urls:
    get:
      summary: Batch Presigned URLs
      description: 'Generates temporary presigned URLs for multiple documents in a single request.


        Filter documents by ticker, document type, and date ranges. Returns paginated results with presigned URLs and document metadata.


        This is useful when you need to download multiple source documents at once, rather than calling the single-document presigned URL endpoint repeatedly.'
      parameters:
      - name: tickers
        in: query
        description: Ticker symbol(s) to filter by. At least one ticker or stock_id is required. Use multiple `tickers` params for multiple tickers (e.g., `?tickers=AAPL&tickers=MSFT`).
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: stock_ids
        in: query
        description: Stock ID(s) to filter by. Can be used instead of or together with `tickers`.
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: doc_type
        in: query
        description: Document type filter (e.g., `filing`, `earnings_call`)
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: doc_sub_type
        in: query
        description: Document sub-type filter (e.g., `10-K`, `10-Q`, `annual_report`, `press_release`)
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: fiscal_period
        in: query
        description: Fiscal period filter. Use nested object notation in the query string (e.g., `fiscal_period[start_time][year]=2024&fiscal_period[start_time][quarter]=1`).
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            start_time:
              type: object
              properties:
                year:
                  type: integer
                  description: Fiscal period start year
                  example: 2023
                quarter:
                  type: integer
                  description: Fiscal period start quarter (1-4)
                  minimum: 1
                  maximum: 4
                  example: 1
            end_time:
              type: object
              properties:
                year:
                  type: integer
                  description: Fiscal period end year
                  example: 2024
                quarter:
                  type: integer
                  description: Fiscal period end quarter (1-4)
                  minimum: 1
                  maximum: 4
                  example: 4
      - name: calendar_period
        in: query
        description: Calendar period filter. Use nested object notation in the query string (e.g., `calendar_period[start_time][year]=2025&calendar_period[start_time][month]=1`).
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            start_time:
              type: object
              properties:
                year:
                  type: integer
                  description: Calendar period start year
                  example: 2025
                month:
                  type: integer
                  description: Calendar period start month (1-12)
                  minimum: 1
                  maximum: 12
                  example: 1
                day:
                  type: integer
                  description: Calendar period start day (1-31, optional — defaults to 1)
                  minimum: 1
                  maximum: 31
                  example: 1
            end_time:
              type: object
              properties:
                year:
                  type: integer
                  description: Calendar period end year
                  example: 2025
                month:
                  type: integer
                  description: Calendar peri

# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/linqalpha/refs/heads/main/openapi/linqalpha-data-api-openapi.yml