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

# Send a message with HTTP SSE streaming response

> Alternative to Socket.IO streaming - uses standard HTTP Server-Sent Events (SSE).
Ideal for server-side integrations, SDKs, and environments where WebSockets aren't available.

## Response Format
Returns `text/event-stream; charset=utf-8` with SSE-formatted JSON chunks.
Each line is prefixed with `data: ` followed by a JSON object and two newlines.

```
data: {"type":"connected","message":"Stream connected"}

data: {"type":"stream","prompt":"The capital","delta":"The capital"}

data: {"type":"stream","prompt":"The capital of France is Paris.","delta":" of France is Paris."}

data: {"type":"tool_call","call_id":"tooluse_abc123","name":"search_uploads","arguments":null,"displayInfo":{"icon":"search","label":"Searching documents"}}

data: {"type":"tool_result","call_id":"tooluse_abc123","name":"search_uploads","arguments":{"query":"France capital"},"response":"...","responseLength":512,"responseDurationMs":150,"success":true}

data: {"type":"complete","success":true,"usage":1234,"outputs":["The capital of France is Paris."],"model":"us.anthropic.claude-sonnet-4-5-20250929-v1:0","cached":0,"completion":42}

data: {"type":"done"}
```

## Event Types
| Type | Description | Key Fields |
|------|-------------|------------|
| `connected` | Stream established | `message` |
| `stream` | Text chunk from AI | `prompt` (cumulative), `delta` (incremental) |
| `tool_call` | Tool invocation started | `call_id`, `name`, `arguments`, `displayInfo` |
| `tool_result` | Tool execution completed | `call_id`, `name`, `response`, `success`, `responseDurationMs` |
| `complete` | Final response with metrics | `success`, `usage`, `outputs`, `model`, `cached`, `completion` |
| `error` | Processing error | `error.message`, `error.status` |
| `done` | Stream ended | _(none)_ |

## Response Headers
```
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
Connection: keep-alive
Content-Encoding: none
Transfer-Encoding: chunked
X-Accel-Buffering: no
```

## Cancellation
Close the HTTP connection to cancel the request. The server will detect the
disconnect and abort any in-progress AI generation.




## OpenAPI

````yaml /mdx/api-reference/runtime/runtime-api.json post /api/ai/personal-stream/qanda-stream
openapi: 3.0.0
info:
  title: Pria Runtime API
  version: 2.0.1
  description: >-
    Pria API Documentation Praxis's developer platform is a core part of our
    mission to empower organizations to grow better. Our APIs are designed to
    enable teams of any shape or size to build robust integrations that help
    them customize and get the most value out of Pria. All Pria APIs are built
    using REST conventions and designed to have a predictable URL structure.
    <br/>  <br/>They use many standard HTTP features, including methods (POST,
    GET, PUT, DELETE) and error response codes.  <br/> <br/>All API calls are
    made under https://hiimpria.ai/api and all responses return standard JSON.
    In these docs, you'll find lists of all available endpoints for a given API,
    along with interactive code blocks for building requests. For walkthroughs
    of basic usage for these APIs, check out the API guides.
servers:
  - url: https://pria.praxislxp.com
    description: Pria API Server
security: []
tags:
  - name: Authentication
    description: User authentication, registration, and password management (/api/auth)
  - name: OAuth
    description: OAuth authentication providers - Google, GitHub, SSO (/api/auth/oauth)
  - name: User
    description: User profile management and account operations (/api/user)
  - name: User Institutions
    description: User institution memberships and switching (/api/user/institution)
  - name: User Tools
    description: Available tools for authenticated users (/api/user/tools)
  - name: Institutions
    description: Institution settings and configuration (/api/user/institution)
  - name: Conversation
    description: AI conversation and Q&A endpoints (/api/ai)
  - name: Realtime
    description: Real-time voice AI and WebRTC sessions (/api/ai/rt)
  - name: Assistant
    description: AI assistant configuration and management (/api/user/assistant)
  - name: History
    description: Conversation history and favorites (/api/user/history)
  - name: RAG
    description: >-
      Document upload, embedding, and retrieval-augmented generation
      (/api/user/files, /api/user/rag)
  - name: Setting
    description: Instance variables and settings management (/api/user/setting)
  - name: Branding
    description: Digital twin branding and customization (/api/agent/branding)
  - name: Agent
    description: Agent engagement and session management (/api/agent)
  - name: SDK Launch
    description: >-
      SDK launch token signing and verification for secure iframe embedding
      (/api/auth/sdk-sign, /api/auth/sdk-verify)
  - name: Testing
    description: Health checks, diagnostics, and test endpoints (/api/test)
  - name: Admin Accounts
    description: Account management for super admins (/api/admin/account)
  - name: Admin Institutions
    description: Institution management for admins (/api/admin/institution)
  - name: Admin Users
    description: User management for admins (/api/admin/user)
  - name: Admin Entitlements
    description: >-
      User-institution relationships and permissions
      (/api/admin/userInstitution)
  - name: Admin Sessions
    description: Session management for admins (/api/admin/session)
  - name: Admin Histories
    description: Conversation history management and analytics (/api/admin/history)
  - name: Admin Assistants
    description: AI assistant management for admins (/api/admin/assistant)
  - name: Admin Questions
    description: Institution question and prompt management (/api/admin/question)
  - name: Admin Tools
    description: Tool configuration management (/api/admin/tool)
  - name: Admin AI Models
    description: AI model configuration (/api/admin/aimodel)
  - name: Admin MCP Servers
    description: Model Context Protocol server management (/api/admin/mcpserver)
  - name: Admin Feedbacks
    description: User feedback management (/api/admin/feedback)
  - name: Admin Uploads
    description: Upload management (/api/admin/upload)
  - name: Admin Charts
    description: Analytics and visualization chart management (/api/admin/chart)
  - name: Audio Notes
    description: Capture and ingest spoken notes into the personal vault
  - name: Memory
    description: User-facing memory parameters (personal + shared instance memory).
  - name: My Data
    description: >-
      GDPR controls — personal-scope counts, async ZIP-by-email export, and
      scoped soft-delete. Every endpoint pins `user = req.user._id` AND
      `institution: null`; institution-scoped data is governed by the
      institution's own retention policy and never reached from here.
  - name: Questions
    description: >-
      User-facing read of the onboarding question bank used by the "create a
      digital twin" wizard.
  - name: Transcription
    description: >-
      One-shot speech-to-text for in-place dictation. Audio blob in, transcript
      out — no Upload / History / RAG embeddings are persisted. Use
      `/audio-notes` for anything durable.
paths:
  /api/ai/personal-stream/qanda-stream:
    post:
      tags:
        - Conversation
      summary: Send a message with HTTP SSE streaming response
      description: >
        Alternative to Socket.IO streaming - uses standard HTTP Server-Sent
        Events (SSE).

        Ideal for server-side integrations, SDKs, and environments where
        WebSockets aren't available.


        ## Response Format

        Returns `text/event-stream; charset=utf-8` with SSE-formatted JSON
        chunks.

        Each line is prefixed with `data: ` followed by a JSON object and two
        newlines.


        ```

        data: {"type":"connected","message":"Stream connected"}


        data: {"type":"stream","prompt":"The capital","delta":"The capital"}


        data: {"type":"stream","prompt":"The capital of France is
        Paris.","delta":" of France is Paris."}


        data:
        {"type":"tool_call","call_id":"tooluse_abc123","name":"search_uploads","arguments":null,"displayInfo":{"icon":"search","label":"Searching
        documents"}}


        data:
        {"type":"tool_result","call_id":"tooluse_abc123","name":"search_uploads","arguments":{"query":"France
        capital"},"response":"...","responseLength":512,"responseDurationMs":150,"success":true}


        data: {"type":"complete","success":true,"usage":1234,"outputs":["The
        capital of France is
        Paris."],"model":"us.anthropic.claude-sonnet-4-5-20250929-v1:0","cached":0,"completion":42}


        data: {"type":"done"}

        ```


        ## Event Types

        | Type | Description | Key Fields |

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

        | `connected` | Stream established | `message` |

        | `stream` | Text chunk from AI | `prompt` (cumulative), `delta`
        (incremental) |

        | `tool_call` | Tool invocation started | `call_id`, `name`,
        `arguments`, `displayInfo` |

        | `tool_result` | Tool execution completed | `call_id`, `name`,
        `response`, `success`, `responseDurationMs` |

        | `complete` | Final response with metrics | `success`, `usage`,
        `outputs`, `model`, `cached`, `completion` |

        | `error` | Processing error | `error.message`, `error.status` |

        | `done` | Stream ended | _(none)_ |


        ## Response Headers

        ```

        Content-Type: text/event-stream; charset=utf-8

        Cache-Control: no-cache, no-transform

        Connection: keep-alive

        Content-Encoding: none

        Transfer-Encoding: chunked

        X-Accel-Buffering: no

        ```


        ## Cancellation

        Close the HTTP connection to cancel the request. The server will detect
        the

        disconnect and abort any in-progress AI generation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QandAStreamRequest'
            example:
              inputs:
                - What is machine learning?
              requestArgs:
                institutionPublicId: f831501f-b645-481a-9cbb-331509aaf8c1
                assistantId: 6856fa89cbafcff8d98680f5
                selectedCourse:
                  course_id: 1750532703472
                  course_name: AI Fundamentals
                ragOnly: false
                ragIgnore: false
                userTimezone: America/New_York
      responses:
        '200':
          description: SSE stream of AI response chunks
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SSEStreamEvent'
              example: >
                data: {"type":"connected","message":"Stream connected"}


                data: {"type":"stream","prompt":"Machine","delta":"Machine"}


                data: {"type":"stream","prompt":"Machine learning is","delta":"
                learning is"}


                data: {"type":"stream","prompt":"Machine learning is a branch of
                AI...","delta":" a branch of AI..."}


                data:
                {"type":"complete","success":true,"usage":1234,"outputs":["Machine
                learning is a branch of
                AI..."],"model":"us.anthropic.claude-sonnet-4-5-20250929-v1:0","cached":0,"completion":42}


                data: {"type":"done"}
        '400':
          description: Invalid request (SSE error event)
          content:
            text/event-stream:
              example: >
                data: {"type":"error","error":{"message":"Input text
                required","status":400}}

                data: {"type":"done"}
        '401':
          description: Authentication required (SSE error event)
          content:
            text/event-stream:
              example: >
                data: {"type":"error","error":{"message":"Authentication
                Required","status":401}}

                data: {"type":"done"}
        '500':
          description: Server error (SSE error event)
          content:
            text/event-stream:
              example: >
                data: {"type":"error","error":{"message":"Internal server
                error","status":500}}

                data: {"type":"done"}
      security:
        - apiKeyAuth: []
components:
  schemas:
    QandAStreamRequest:
      type: object
      description: Request payload for SSE streaming Q&A
      required:
        - inputs
      properties:
        inputs:
          type: array
          items:
            type: string
          description: User messages to send to the AI
          example:
            - What is machine learning?
        requestArgs:
          type: object
          description: Optional context arguments
          properties:
            selectedCourse:
              $ref: '#/components/schemas/ConversationContext'
            ragOnly:
              type: boolean
              description: Return only RAG results without AI generation
              default: false
            ragIgnore:
              type: boolean
              description: Skip RAG search entirely (LLM answers without RAG context)
              default: false
            userISODate:
              type: string
              format: date-time
              description: User's current timestamp
            userTimezone:
              type: string
              description: User's IANA timezone
            userGPSCoordinates:
              $ref: '#/components/schemas/GPSCoordinates'
            institutionPublicId:
              type: string
              format: uuid
              description: >
                Specifies the digital twin (institution) to send the command to.

                The server validates that the authenticated user has a valid
                membership

                in the specified institution. When found, the user's active
                institution

                is switched to this institution in their profile data for the
                duration

                of the request.
            assistantId:
              type: string
              description: >
                ObjectId of the assistant to use for this request.

                Takes priority over selectedCourse.assistant._id (legacy).

                If not provided, the assistant is resolved from selectedCourse
                or

                the most recent history record for the conversation.
    SSEStreamEvent:
      type: object
      description: |
        Server-Sent Event payload structure for HTTP streaming.
        Each event is a JSON object sent as `data: {json}\n\n`.
        The `type` field determines which other fields are present.
      properties:
        type:
          type: string
          enum:
            - connected
            - stream
            - tool_call
            - tool_result
            - complete
            - error
            - done
          description: >
            Event type indicator:

            - `connected`: Stream established successfully

            - `stream`: AI-generated text chunk (cumulative + delta)

            - `tool_call`: Tool/function invocation started (RAG, web search,
            etc.)

            - `tool_result`: Tool/function execution completed with results

            - `complete`: Final response with usage metrics and full output

            - `error`: Error occurred during processing

            - `done`: Stream terminated — no more events will follow
    ConversationContext:
      type: object
      description: Context for a conversation session (course/topic)
      properties:
        course_id:
          type: number
          description: Unique conversation/course identifier (epoch timestamp)
          example: 1750532703472
        course_name:
          type: string
          description: Display name for the conversation
          example: Research Project Discussion
        assistant:
          $ref: '#/components/schemas/AssistantReference'
        history_count:
          type: integer
          description: Number of dialogue entries in this conversation
          example: 15
        last_dialogue_date:
          type: string
          format: date-time
          description: Timestamp of most recent message
    GPSCoordinates:
      type: object
      description: Geographic location data from device
      properties:
        accuracy:
          type: number
          description: GPS accuracy in meters
          example: 21126.84
        latitude:
          type: number
          description: Latitude coordinate (-90 to 90)
          example: -21.282816
        longitude:
          type: number
          description: Longitude coordinate (-180 to 180)
          example: 55.4139648
        altitude:
          type: number
          nullable: true
          description: Altitude in meters above sea level
        altitudeAccuracy:
          type: number
          nullable: true
          description: Altitude accuracy in meters
        heading:
          type: number
          nullable: true
          description: Direction of travel in degrees (0-360)
        speed:
          type: number
          nullable: true
          description: Speed in meters per second
    AssistantReference:
      type: object
      description: Reference to an AI assistant for conversation context
      properties:
        _id:
          type: string
          description: Assistant unique identifier (MongoDB ObjectId)
          example: 6856fa89cbafcff8d98680f5
        name:
          type: string
          description: Assistant display name
          example: Research Assistant
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-access-token
      description: JWT token passed in x-access-token header

````