spb/vquant Public MIT

1<!--2  =============================================================================3   VibeQuant (vquant) — AI-Powered Financial Intelligence Platform4  -----------------------------------------------------------------------------5   File:      docs/API_REFERENCE.md67   Author:    Simon-Pierre Boucher8   Contact:   contact@spboucher.ai9   Website:   https://www.spboucher.ai10   Demo:      https://www.vquant.ai11   License:   MIT (see LICENSE)1213   Copyright © 2026 Simon-Pierre Boucher. All rights reserved.14  =============================================================================15-->1617# API Reference1819Complete reference for all VibeQuant API endpoints.2021Base URL: `http://localhost:5000` (development) or `https://www.vquant.ai` (production)2223---2425## Chat (SSE Streaming)2627### `POST /api/chat`2829Main AI chat endpoint with real-time streaming via Server-Sent Events.3031**Request Body** (validated with Zod):3233```json34{35  "query": "Analyze AAPL stock",              // required, 1-10000 chars36  "history": [                                 // optional, default []37    { "question": "Previous Q", "answer": "Previous A" }38  ],39  "sessionId": "uuid-string",                 // optional, auto-generated40  "imageData": "base64-encoded-image",         // optional41  "imageMimeType": "image/png"                 // optional42}43```4445**Response**: SSE stream with events:4647| Event Type | Payload | Description |48|------------|---------|-------------|49| `text` | `{ content: string }` | Incremental answer token |50| `sources` | `{ sources: SearchResult[] }` | Web search results |51| `status` | `{ message: string }` | Status update |52| `search_queries` | `{ queries: string[], message: string }` | Search queries planned |53| `search_progress` | `{ index, total, query }` | Search execution progress |54| `search_result` | `{ index, results }` | Individual search result |55| `tool_start` | `{ tool: string, input: object }` | Tool execution started |56| `tool_complete` | `{ tool: string, duration: number }` | Tool execution completed |57| `tool_error` | `{ tool: string, error: string }` | Tool execution failed |58| `tool_result` | `{ tool: string, result: object }` | Tool result data |59| `python_code` | `{ code: string }` | Python code executed |60| `custom_python_figures` | `{ figureId, figures[], figureUrls[], output, description }` | Generated charts |61| `done` | `{ sessionId: string }` | Stream complete |62| `error` | `{ error: string }` | Fatal error |6364### `POST /api/speech-to-text`6566Transcribe audio to text using ElevenLabs Scribe v2.6768**Request**: `multipart/form-data` with `audio` file field (max 25MB)6970**Response**:71```json72{73  "text": "transcribed text content"74}75```7677---7879## Authentication8081### `POST /api/auth/register`8283Create a new user account.8485**Request Body**:86```json87{88  "name": "Alice"   // min 2 characters89}90```9192**Response** `200`:93```json94{95  "user": { "id": "uuid", "displayName": "Alice" },96  "token": "vquant-abc1234"97}98```99100### `POST /api/auth/login`101102Authenticate with token.103104**Request Body**:105```json106{107  "token": "vquant-abc1234"108}109```110111**Response** `200`:112```json113{114  "user": { "id": "uuid", "displayName": "Alice" }115}116```117118**Response** `401`:119```json120{ "error": "Token invalide" }121```122123### `POST /api/auth/logout`124125End the current session.126127**Response** `200`:128```json129{ "success": true }130```131132### `GET /api/auth/me`133134Get current authenticated user.135136**Response** `200`:137```json138{139  "user": { "id": "uuid", "displayName": "Alice" }140}141// or142{143  "user": null144}145```146147---148149## Shared Reports150151### `GET /api/shared-reports`152153List all shared reports (for showcase/explore page).154155**Response** `200`: Array of reports with truncated answers (500 chars).156157### `POST /api/share`158159Create a shareable report.160161**Request Body**:162```json163{164  "question": "Analyze AAPL",165  "answer": "Apple Inc is...",166  "toolResults": [...],             // optional167  "sources": [...],                 // optional168  "customPythonFigures": [...]      // optional169}170```171172**Response** `200`:173```json174{ "shareId": "a1b2c3d4" }175```176177### `GET /api/share/:shareId`178179Get a shared report by its ID.180181**Response** `200`:182```json183{184  "question": "...",185  "answer": "...",186  "toolResults": [],187  "sources": [],188  "customPythonFigures": null,189  "createdAt": "2026-02-25T..."190}191```192193---194195## Sessions196197### `GET /api/sessions`198199List all conversation sessions for the current user.200201**Response** `200`: Array of `{ sessionId, title, createdAt, updatedAt }`.202203### `GET /api/sessions/:sessionId`204205Get a specific session with full message history.206207**Response** `200`:208```json209{210  "sessionId": "...",211  "title": "...",212  "messages": "[{\"question\":\"...\",\"answer\":\"...\"}]",213  "createdAt": "...",214  "updatedAt": "..."215}216```217218---219220## Document Generation221222### `POST /api/generate-pdf`223224Generate a PDF report from markdown.225226**Request Body**: `{ "question": "...", "answer": "..." }`227228**Response**: Binary PDF file (`application/pdf`).229230### `POST /api/generate-docx`231232Generate a DOCX document from markdown.233234**Request Body**: `{ "question": "...", "answer": "..." }`235236**Response**: Binary DOCX file.237238### `POST /api/convert-to-slides`239240Generate a Beamer LaTeX PDF presentation.241242**Request Body**:243```json244{245  "question": "...",246  "answer": "...",247  "author": "Simon-Pierre Boucher",248  "company": "VibeQuant",              // optional, default "VibeQuant"249  "figureUrls": ["url1", "url2"]       // optional250}251```252253**Response**: Binary PDF file.254255### `GET /api/download/:filename`256257Download a generated data file (CSV, XLSX, JSON, TXT).258259**Security**: Only alphanumeric characters, dots, underscores, and hyphens allowed in filename.260261---262263## Financial Data (FMP)264265All FMP endpoints are `GET` requests. Symbol is passed as a URL parameter.266267### Market Overview268269| Endpoint | Description |270|----------|-------------|271| `GET /api/fmp/market-hours` | Current market hours |272| `GET /api/fmp/gainers` | Top gaining stocks |273| `GET /api/fmp/losers` | Top losing stocks |274| `GET /api/fmp/actives` | Most active stocks |275276### Quotes & Prices277278| Endpoint | Query Params | Description |279|----------|-------------|-------------|280| `GET /api/fmp/quote/:symbol` | | Real-time quote |281| `GET /api/fmp/stock-quote/:symbol` | | Stock quote (alias) |282| `GET /api/fmp/company-profile/:symbol` | | Full company profile |283| `GET /api/fmp/historical-price/:symbol` | | Historical daily prices |284| `GET /api/fmp/intraday/:symbol` | `interval=5min` | Intraday prices |285286### Financial Statements287288| Endpoint | Query Params | Description |289|----------|-------------|-------------|290| `GET /api/fmp/income-statement/:symbol` | `period=annual\|quarter`, `limit=5` | Income statement |291| `GET /api/fmp/balance-sheet/:symbol` | `period`, `limit` | Balance sheet |292| `GET /api/fmp/cash-flow/:symbol` | `period`, `limit` | Cash flow statement |293| `GET /api/fmp/key-metrics/:symbol` | `period`, `limit` | Key financial metrics |294| `GET /api/fmp/financial-ratios/:symbol` | `period`, `limit` | Financial ratios |295296### Analysis297298| Endpoint | Description |299|----------|-------------|300| `GET /api/fmp/analyst-estimates/:symbol` | Analyst estimates |301| `GET /api/fmp/price-target/:symbol` | Price targets |302| `GET /api/fmp/price-target-summary/:symbol` | Price target summary |303| `GET /api/fmp/upgrades-downgrades/:symbol` | Analyst upgrades/downgrades |304| `GET /api/fmp/earnings-surprises/:symbol` | Earnings surprises |305| `GET /api/fmp/esg-score/:symbol` | ESG score |306307### Other Data308309| Endpoint | Description |310|----------|-------------|311| `GET /api/fmp/dividend-history/:symbol` | Dividend history |312| `GET /api/fmp/institutional-holders/:symbol` | Top institutional holders |313| `GET /api/fmp/financial-news/:symbol` | Recent financial news |314| `GET /api/fmp/insider-trading/:symbol` | Insider trades |315316### Chart Data317318| Endpoint | Query Params | Description |319|----------|-------------|-------------|320| `GET /api/fmp/chart/light/:symbol` | `from`, `to` | Lightweight OHLCV |321| `GET /api/fmp/chart/full/:symbol` | `from`, `to` | Full OHLCV + indicators |322| `GET /api/fmp/chart/intraday/:symbol` | `interval`, `from`, `to`, `nonadjusted` | Intraday OHLCV |323324---325326## Analytics327328### `POST /api/analytics/heartbeat`329330Update user activity tracking.331332**Request Body**:333```json334{335  "sessionId": "browser-session-id",336  "status": "idle|generating|error",337  "currentQuery": "Current question...",338  "userId": "user-id-if-logged-in"339}340```341342### `GET /api/analytics/real-time-stats`343344Public endpoint for real-time platform statistics.345346**Response** `200`:347```json348{349  "activeUsers": { "total": 5, "generating": 2 },350  "sessions": { "total": 150, "today": 12 },351  "tokens": { "total": 5000000, "input": 3000000, "output": 2000000 },352  "cost": { "total": 45.50, "today": 3.20 },353  "errors": { "lastHour": 1, "rate": 0.5 }354}355```356357### `GET /api/analytics/active-users` (admin)358359Detailed active user list with status and queries.360361### `GET /api/analytics/metrics` (admin)362363Historical metrics with time range filtering.364365**Query Params**: `periodType=minute|hour|day`, `limit=60`366367---368369## Admin370371All admin endpoints require the `requireAdmin` middleware.372373| Method | Endpoint | Description |374|--------|----------|-------------|375| `POST` | `/api/admin/login` | Set admin session |376| `GET` | `/api/admin/database` | Full database dump with metrics |377| `DELETE` | `/api/admin/users/:id` | Delete user + their sessions |378| `DELETE` | `/api/admin/sessions/:id` | Delete conversation session |379| `DELETE` | `/api/admin/reports/:id` | Delete shared report |380