# API Reference

Complete reference for all VibeQuant API endpoints.

Base URL: http://localhost:5000 (development) or https://www.vquant.ai (production)

# Chat (SSE Streaming)

# POST /api/chat

Main AI chat endpoint with real-time streaming via Server-Sent Events.

Request Body (validated with Zod):

{
  "query": "Analyze AAPL stock",              // required, 1-10000 chars
  "history": [                                 // optional, default []
    { "question": "Previous Q", "answer": "Previous A" }
  ],
  "sessionId": "uuid-string",                 // optional, auto-generated
  "imageData": "base64-encoded-image",         // optional
  "imageMimeType": "image/png"                 // optional
}

Response: SSE stream with events:

# POST /api/speech-to-text

Transcribe audio to text using ElevenLabs Scribe v2.

Request: multipart/form-data with audio file field (max 25MB)

Response:

{
  "text": "transcribed text content"
}

# Authentication

# POST /api/auth/register

Create a new user account.

Request Body:

{
  "name": "Alice"   // min 2 characters
}

Response 200:

{
  "user": { "id": "uuid", "displayName": "Alice" },
  "token": "vquant-abc1234"
}

# POST /api/auth/login

Authenticate with token.

Request Body:

{
  "token": "vquant-abc1234"
}

Response 200:

{
  "user": { "id": "uuid", "displayName": "Alice" }
}

Response 401:

{ "error": "Token invalide" }

# POST /api/auth/logout

End the current session.

Response 200:

{ "success": true }

# GET /api/auth/me

Get current authenticated user.

Response 200:

{
  "user": { "id": "uuid", "displayName": "Alice" }
}
// or
{
  "user": null
}

# Shared Reports

# GET /api/shared-reports

List all shared reports (for showcase/explore page).

Response 200: Array of reports with truncated answers (500 chars).

# POST /api/share

Create a shareable report.

Request Body:

{
  "question": "Analyze AAPL",
  "answer": "Apple Inc is...",
  "toolResults": [...],             // optional
  "sources": [...],                 // optional
  "customPythonFigures": [...]      // optional
}

Response 200:

{ "shareId": "a1b2c3d4" }

# GET /api/share/:shareId

Get a shared report by its ID.

Response 200:

{
  "question": "...",
  "answer": "...",
  "toolResults": [],
  "sources": [],
  "customPythonFigures": null,
  "createdAt": "2026-02-25T..."
}

# Sessions

# GET /api/sessions

List all conversation sessions for the current user.

Response 200: Array of { sessionId, title, createdAt, updatedAt }.

# GET /api/sessions/:sessionId

Get a specific session with full message history.

Response 200:

{
  "sessionId": "...",
  "title": "...",
  "messages": "[{\"question\":\"...\",\"answer\":\"...\"}]",
  "createdAt": "...",
  "updatedAt": "..."
}

# Document Generation

# POST /api/generate-pdf

Generate a PDF report from markdown.

Request Body: { "question": "...", "answer": "..." }

Response: Binary PDF file (application/pdf).

# POST /api/generate-docx

Generate a DOCX document from markdown.

Request Body: { "question": "...", "answer": "..." }

Response: Binary DOCX file.

# POST /api/convert-to-slides

Generate a Beamer LaTeX PDF presentation.

Request Body:

{
  "question": "...",
  "answer": "...",
  "author": "Simon-Pierre Boucher",
  "company": "VibeQuant",              // optional, default "VibeQuant"
  "figureUrls": ["url1", "url2"]       // optional
}

Response: Binary PDF file.

# GET /api/download/:filename

Download a generated data file (CSV, XLSX, JSON, TXT).

Security: Only alphanumeric characters, dots, underscores, and hyphens allowed in filename.

# Financial Data (FMP)

All FMP endpoints are GET requests. Symbol is passed as a URL parameter.

# Market Overview

# Quotes & Prices

# Financial Statements

# Analysis

# Other Data

# Chart Data

# Analytics

# POST /api/analytics/heartbeat

Update user activity tracking.

Request Body:

{
  "sessionId": "browser-session-id",
  "status": "idle|generating|error",
  "currentQuery": "Current question...",
  "userId": "user-id-if-logged-in"
}

# GET /api/analytics/real-time-stats

Public endpoint for real-time platform statistics.

Response 200:

{
  "activeUsers": { "total": 5, "generating": 2 },
  "sessions": { "total": 150, "today": 12 },
  "tokens": { "total": 5000000, "input": 3000000, "output": 2000000 },
  "cost": { "total": 45.50, "today": 3.20 },
  "errors": { "lastHour": 1, "rate": 0.5 }
}

# GET /api/analytics/active-users (admin)

Detailed active user list with status and queries.

# GET /api/analytics/metrics (admin)

Historical metrics with time range filtering.

Query Params: periodType=minute|hour|day, limit=60

# Admin

All admin endpoints require the requireAdmin middleware.