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

# Generate Briefing

> Generate a briefing on-demand from an ad-hoc prompt via Server-Sent Events streaming. The prompt (`query`) is run through the briefing engine (mode=briefing) — the same output family as your scheduled briefings (depth, formatting, citations). Stateless: send a fresh prompt each call.

Generate a briefing on-demand from an ad-hoc prompt via Server-Sent Events streaming. The prompt (`query`) is run through the briefing engine — the same engine behind your scheduled briefings — so the output matches your scheduled briefing's depth, formatting, and citations. Send a fresh prompt on each call.

## Request

`query` (required) is your briefing prompt. All other fields are optional:

* `tickers` / `stock_ids` — securities to scope the briefing to.
* `frequency` — `daily` (default), `weekly`, or `monthly`; sets the data window (last 1 / 7 / 30 days, anchored at "now").
* `timezone` — IANA timezone (e.g. `Asia/Shanghai`) used for the window and timestamps. Defaults to `UTC`.
* `language` — output language; auto-detected from the prompt when omitted.
* `previous_summary` — the prior briefing's content, to carry formatting/continuity across calls (optional).

## Event Flow

```
status → [status]* → answer → status:finish
```

Progress `status` events stream while the briefing runs, followed by a single `answer` event carrying the **full** briefing markdown (with linked `[N](url)` citations), then `status:finish`. Read the content from the `answer` event's `answer_piece`. The full content arrives once (not token-by-token), because inline citations are resolved only after the briefing completes.

On failure, a single `status` event with `status: "error"` (carrying a `code`) is emitted instead of `answer`.

This endpoint is stateless: each call generates a standalone briefing from the prompt you send.

## Authentication

For platform API keys, pass `organization_id`, `user_id`, and `user_email` in the request body to select which user the briefing is generated for. Organization-bound keys resolve the user automatically.


## OpenAPI

````yaml POST /v1/briefings/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:
  /v1/briefings/sse:
    post:
      tags:
        - Briefing
      summary: Generate Briefing
      description: >-
        Generate a briefing on-demand from an ad-hoc prompt via Server-Sent
        Events streaming. The prompt (`query`) is run through the briefing
        engine (mode=briefing) — the same output family as your scheduled
        briefings (depth, formatting, citations). Stateless: send a fresh prompt
        each call.
      operationId: briefingSse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: >-
                    The ad-hoc briefing prompt (used as the briefing topic), run
                    through the briefing engine
                tickers:
                  type: array
                  items:
                    type: string
                  description: Optional ticker symbols to scope the briefing
                stock_ids:
                  type: array
                  items:
                    type: string
                  description: Optional internal stock ids to scope the briefing
                frequency:
                  type: string
                  enum:
                    - daily
                    - weekly
                    - monthly
                  description: >-
                    Data window (last 1 / 7 / 30 days, anchored at now).
                    Defaults to daily.
                language:
                  type: string
                  description: Output language; auto-detected from the prompt when omitted
                timezone:
                  type: string
                  description: >-
                    IANA timezone (e.g. Asia/Shanghai) for the window and
                    timestamps. Defaults to UTC.
                previous_summary:
                  type: string
                  description: >-
                    Prior briefing content, to carry continuity across calls
                    (optional)
                conversation_id:
                  type: string
                  nullable: true
                  description: Deprecated and ignored; this endpoint is stateless
                organization_id:
                  type: string
                  description: Organization ID for platform API keys
                user_id:
                  type: string
                  description: User ID (customer_id) for platform API keys
                user_email:
                  type: string
                  description: User email for platform API keys
                user_name:
                  type: string
                  description: User name for platform API keys
      responses:
        '200':
          description: >-
            SSE stream of briefing events, each sent as `data: {json}\n\n`.
            Sequence: status → [status]* → answer → status:finish. A keepalive
            is sent as a status event roughly every 30s. On failure a single
            status event with status "error" (carrying a code) is emitted
            instead of answer. The answer arrives once (full content), not
            token-by-token, because inline citations are resolved only after the
            briefing completes.
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AnalyticsStatusEvent'
                  - $ref: '#/components/schemas/AnalyticsAnswerEvent'
              examples:
                status_start:
                  summary: Status
                  description: >-
                    Progress update while the briefing runs (label in
                    data.message)
                  value:
                    event_name: status
                    data:
                      status: start
                      message: Searching news
                answer:
                  summary: Answer (full content)
                  description: >-
                    The full briefing markdown with linked [N](url) citations,
                    emitted once
                  value:
                    event_name: answer
                    data:
                      answer_piece: >-
                        ## Market Overview\n\nAsian equities traded mixed
                        overnight... [1](https://example.com)
                status_finish:
                  summary: Status Finish
                  description: Stream complete — no more events after this
                  value:
                    event_name: status
                    data:
                      status: finish
                status_error:
                  summary: Status Error
                  description: Terminal failure instead of answer (carries an error code)
                  value:
                    event_name: status
                    data:
                      status: error
                      error:
                        code: EMPTY_CONTENT
                        msg: Briefing could not be generated.
        '400':
          description: Bad Request - Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST_BODY
                  msg: query is required and must be a string
                  message: query is required and must be a string
                payload: null
        '401':
          description: Unauthorized - Invalid or missing API key.
          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:
    AnalyticsStatusEvent:
      description: >-
        Stream status event indicating start, finish, or keep_alive of the
        analytics stream.
      allOf:
        - $ref: '#/components/schemas/AnalyticsSseEvent'
        - properties:
            event_name:
              enum:
                - status
            data:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum:
                    - start
                    - finish
                    - keep_alive
                  description: >-
                    Stream lifecycle status. 'keep_alive' is sent periodically
                    during long tool execution gaps.
    AnalyticsAnswerEvent:
      description: >-
        Final answer event. Contains the complete answer in a single event (not
        streamed incrementally).
      allOf:
        - $ref: '#/components/schemas/AnalyticsSseEvent'
        - properties:
            event_name:
              enum:
                - answer
            data:
              type: object
              required:
                - answer_piece
              properties:
                answer_piece:
                  type: string
                  description: >-
                    The complete final answer content. Unlike other SSE
                    endpoints, analytics sends the full answer in a single event
                    rather than streaming it incrementally.
    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
    AnalyticsSseEvent:
      type: object
      description: Base structure for all Analytics SSE events
      required:
        - event_name
        - data
      properties:
        event_name:
          type: string
          enum:
            - message
            - status
            - think
            - tool_use_block
            - tool_result_block
            - answer
            - keepalive
          description: Type of event in the analytics stream
        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

````