2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"] 4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""] 5:I[4126,[],""] 7:I[9630,[],""] 8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"] 9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"] a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"] b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"] 3:T37a6, # VoiceAssist REST API Reference **Version:** 2.0 **Base URL:** `https://assist.asimo.io/api` (production) or `http://localhost:8000/api` (development) **Last Updated:** 2025-11-27 > **See Also:** [Auto-generated API Routes](API_ROUTES.md) - Complete route listing from OpenAPI spec --- ## Overview The VoiceAssist API provides a comprehensive set of endpoints for building medical AI assistant applications. All endpoints follow REST conventions and return JSON responses wrapped in a standard envelope format. ### Authentication Most endpoints require JWT authentication. Include the access token in the `Authorization` header: ``` Authorization: Bearer ``` ### Response Envelope All responses follow this structure: ```json { "success": true, "data": { ... }, "error": null, "meta": { "request_id": "uuid", "timestamp": "ISO-8601" } } ``` ### Rate Limiting Rate limits are applied per IP address. Headers returned: - `X-RateLimit-Limit`: Maximum requests allowed - `X-RateLimit-Remaining`: Requests remaining - `X-RateLimit-Reset`: Unix timestamp when limit resets --- ## Authentication (`/api/auth`) ### Register User ``` POST /api/auth/register ``` Create a new user account. **Rate Limit:** 5/hour per IP **Request Body:** ```json { "email": "user@example.com", "password": "securePassword123", "full_name": "John Doe" } ``` **Response (201):** ```json { "id": "uuid", "email": "user@example.com", "full_name": "John Doe", "is_active": true, "is_admin": false, "created_at": "2025-11-27T10:00:00Z" } ``` --- ### Login ``` POST /api/auth/login ``` Authenticate and receive JWT tokens. **Rate Limit:** 10/minute per IP **Request Body:** ```json { "email": "user@example.com", "password": "securePassword123" } ``` **Response (200):** ```json { "access_token": "eyJhbG...", "refresh_token": "eyJhbG...", "token_type": "bearer", "expires_in": 300 } ``` --- ### Refresh Token ``` POST /api/auth/refresh ``` Get a new access token using a refresh token. **Request Body:** ```json { "refresh_token": "eyJhbG..." } ``` **Response (200):** ```json { "access_token": "eyJhbG...", "refresh_token": "eyJhbG...", "token_type": "bearer", "expires_in": 300 } ``` --- ### Logout ``` POST /api/auth/logout ``` Revoke current tokens. **Headers:** `Authorization: Bearer ` **Response (200):** ```json { "message": "Successfully logged out" } ``` --- ### Get Current User ``` GET /api/auth/me ``` Get authenticated user's information. **Headers:** `Authorization: Bearer ` **Response (200):** ```json { "id": "uuid", "email": "user@example.com", "full_name": "John Doe", "is_active": true, "is_admin": false, "admin_role": "user", "created_at": "2025-11-27T10:00:00Z", "last_login": "2025-11-27T12:00:00Z" } ``` --- ## User Management (`/api/users`) ### Get Current User Profile ``` GET /api/users/me ``` **Headers:** `Authorization: Bearer ` --- ### Update Current User Profile ``` PUT /api/users/me ``` **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "full_name": "John Updated", "email": "newemail@example.com" } ``` --- ### Change Password ``` POST /api/users/me/change-password ``` **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "old_password": "currentPassword", "new_password": "newSecurePassword123" } ``` --- ### Delete Account ``` DELETE /api/users/me ``` Permanently delete user account. **Headers:** `Authorization: Bearer ` --- ### List Users (Admin) ``` GET /api/users?offset=0&limit=20 ``` **Headers:** `Authorization: Bearer ` **Query Parameters:** - `offset` (int): Pagination offset (default: 0) - `limit` (int): Page size (default: 20, max: 100) --- ### Get User by ID (Admin) ``` GET /api/users/{user_id} ``` **Headers:** `Authorization: Bearer ` --- ### Update User (Admin) ``` PATCH /api/users/{user_id} ``` **Headers:** `Authorization: Bearer ` --- ### Activate User (Admin) ``` PUT /api/users/{user_id}/activate ``` **Headers:** `Authorization: Bearer ` --- ### Deactivate User (Admin) ``` PUT /api/users/{user_id}/deactivate ``` **Headers:** `Authorization: Bearer ` --- ### Promote to Admin (Admin) ``` PUT /api/users/{user_id}/promote-admin ``` **Headers:** `Authorization: Bearer ` --- ### Revoke Admin (Admin) ``` PUT /api/users/{user_id}/revoke-admin ``` **Headers:** `Authorization: Bearer ` --- ## Conversations (`/conversations`) ### List Conversations ``` GET /conversations?page=1&pageSize=20 ``` **Headers:** `Authorization: Bearer ` **Query Parameters:** - `page` (int): Page number (default: 1) - `pageSize` (int): Items per page (default: 20) - `archived` (bool): Filter archived conversations - `folderId` (string): Filter by folder **Response (200):** ```json { "items": [ { "id": "uuid", "userId": "uuid", "title": "Medical Inquiry", "archived": false, "messageCount": 5, "folderId": null, "createdAt": "2025-11-27T10:00:00Z", "updatedAt": "2025-11-27T12:00:00Z" } ], "total": 42, "page": 1, "pageSize": 20 } ``` --- ### Create Conversation ``` POST /conversations ``` **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "title": "New Medical Discussion", "folder_id": "optional-folder-uuid" } ``` --- ### Get Conversation ``` GET /conversations/{conversation_id} ``` **Headers:** `Authorization: Bearer ` --- ### Update Conversation ``` PUT /conversations/{conversation_id} ``` **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "title": "Updated Title", "archived": false, "folder_id": "new-folder-uuid" } ``` --- ### Delete Conversation ``` DELETE /conversations/{conversation_id} ``` **Headers:** `Authorization: Bearer ` --- ### Create Branch ``` POST /conversations/{conversation_id}/branches ``` Fork a conversation from a specific message. **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "parent_message_id": "message-uuid", "initial_message": "Optional first message in branch" } ``` --- ### List Branches ``` GET /conversations/{conversation_id}/branches ``` **Headers:** `Authorization: Bearer ` --- ### Get Messages ``` GET /conversations/{conversation_id}/messages?branch_id=main ``` **Headers:** `Authorization: Bearer ` **Query Parameters:** - `branch_id` (string): Branch identifier (default: "main") - `limit` (int): Maximum messages to return --- ## Admin Panel (`/api/admin/panel`) ### Dashboard Summary ``` GET /api/admin/panel/summary ``` Get dashboard metrics summary. **Headers:** `Authorization: Bearer ` **Response (200):** ```json { "users": { "total": 150, "active": 142, "admins": 3 }, "conversations": { "total": 1250, "today": 45 }, "system": { "status": "healthy", "uptime": 864000 } } ``` --- ### WebSocket Status ``` GET /api/admin/panel/websocket-status ``` Get real-time connection status. **Headers:** `Authorization: Bearer ` --- ### List Users ``` GET /api/admin/panel/users?offset=0&limit=20 ``` Paginated user list with statistics. **Headers:** `Authorization: Bearer ` --- ### Get User Details ``` GET /api/admin/panel/users/{user_id} ``` **Headers:** `Authorization: Bearer ` --- ### Update User ``` PUT /api/admin/panel/users/{user_id} ``` **Headers:** `Authorization: Bearer ` --- ### Delete User ``` DELETE /api/admin/panel/users/{user_id} ``` **Headers:** `Authorization: Bearer ` --- ### User Role History ``` GET /api/admin/panel/users/{user_id}/role-history ``` **Headers:** `Authorization: Bearer ` --- ### Account Lock Reasons ``` GET /api/admin/panel/users/{user_id}/lock-reasons ``` **Headers:** `Authorization: Bearer ` --- ### System Metrics ``` GET /api/admin/panel/metrics ``` **Headers:** `Authorization: Bearer ` --- ### Audit Logs ``` GET /api/admin/panel/audit-logs?page=1&limit=50 ``` **Headers:** `Authorization: Bearer ` **Query Parameters:** - `page` (int): Page number - `limit` (int): Items per page - `action` (string): Filter by action type - `user_id` (string): Filter by user --- ### Export Audit Logs ``` GET /api/admin/panel/audit-logs/export?format=csv ``` **Headers:** `Authorization: Bearer ` --- ## Knowledge Base Admin (`/api/admin/kb`) ### List Documents ``` GET /api/admin/kb/documents?offset=0&limit=20 ``` **Headers:** `Authorization: Bearer ` **Query Parameters:** - `offset` (int): Pagination offset - `limit` (int): Page size - `status` (string): Filter by status (uploaded, processing, indexed, failed) --- ### Upload Document ``` POST /api/admin/kb/documents Content-Type: multipart/form-data ``` Upload a document for indexing. **Headers:** `Authorization: Bearer ` **Form Data:** - `file`: PDF or TXT file (max 50MB) - `title` (string): Document title - `category` (string): Document category --- ### Get Document Details ``` GET /api/admin/kb/documents/{document_id} ``` **Headers:** `Authorization: Bearer ` --- ### Delete Document ``` DELETE /api/admin/kb/documents/{document_id} ``` **Headers:** `Authorization: Bearer ` --- ### Reindex Document ``` POST /api/admin/kb/documents/{document_id}/reindex ``` **Headers:** `Authorization: Bearer ` --- ## Cache Management (`/api/admin/cache`) ### Cache Statistics ``` GET /api/admin/cache/stats ``` **Headers:** `Authorization: Bearer ` **Response (200):** ```json { "redis": { "connected": true, "used_memory": "15MB", "keys": 1250 }, "l1_cache": { "size": 500, "hits": 12500, "misses": 250 } } ``` --- ### Clear Cache ``` POST /api/admin/cache/clear ``` Clear all caches. **Headers:** `Authorization: Bearer ` --- ### Invalidate Cache Pattern ``` POST /api/admin/cache/invalidate ``` Invalidate specific cache keys. **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "pattern": "user:*" } ``` --- ## Feature Flags (`/api/admin/feature-flags`) ### List Feature Flags ``` GET /api/admin/feature-flags ``` **Headers:** `Authorization: Bearer ` **Response (200):** ```json { "flags": [ { "name": "voice_mode", "enabled": true, "description": "Enable voice input mode", "rollout_percentage": 100, "updated_at": "2025-11-27T10:00:00Z" } ] } ``` --- ### Get Feature Flag ``` GET /api/admin/feature-flags/{flag_name} ``` **Headers:** `Authorization: Bearer ` --- ### Create Feature Flag ``` POST /api/admin/feature-flags ``` **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "name": "new_feature", "enabled": false, "description": "Description of the feature", "rollout_percentage": 0 } ``` --- ### Update Feature Flag ``` PATCH /api/admin/feature-flags/{flag_name} ``` **Headers:** `Authorization: Bearer ` **Request Body:** ```json { "enabled": true, "rollout_percentage": 50 } ``` --- ### Delete Feature Flag ``` DELETE /api/admin/feature-flags/{flag_name} ``` **Headers:** `Authorization: Bearer ` --- ### Toggle Feature Flag ``` POST /api/admin/feature-flags/{flag_name}/toggle ``` Quick toggle for feature flags. **Headers:** `Authorization: Bearer ` --- ## Health Checks ### Liveness Check ``` GET /health ``` Basic health check. Returns 200 if service is running. **Rate Limit:** 100/minute **Response (200):** ```json { "status": "healthy", "version": "2.0.0", "timestamp": 1732703400.123 } ``` --- ### Readiness Check ``` GET /ready ``` Checks all dependencies (PostgreSQL, Redis, Qdrant, Nextcloud). **Rate Limit:** 100/minute **Response (200):** ```json { "status": "ready", "checks": { "postgres": true, "redis": true, "qdrant": true, "nextcloud": true }, "timestamp": 1732703400.123 } ``` **Response (503):** If any dependency is unavailable. --- ## Metrics ### Prometheus Metrics ``` GET /metrics ``` Prometheus-formatted metrics for monitoring. --- ## Voice Endpoints (`/api/voice`) ### Start Voice Session ``` POST /api/voice/session ``` Initialize a voice interaction session. **Headers:** `Authorization: Bearer ` --- ### Send Audio ``` POST /api/voice/audio Content-Type: multipart/form-data ``` Send audio for transcription and processing. **Headers:** `Authorization: Bearer ` --- ## WebSocket Realtime (`/ws`) ### Connect ``` WS /ws?token= ``` Establish WebSocket connection for real-time chat. ### Events **Client → Server:** - `message_send`: Send a new message - `typing_start`: Start typing indicator - `typing_stop`: Stop typing indicator **Server → Client:** - `connected`: Connection established - `chunk`: Streaming response chunk - `message_done`: Complete message with citations - `error`: Error notification --- ## Error Codes | Code | HTTP Status | Description | | ------------------ | ----------- | --------------------------------- | | `UNAUTHORIZED` | 401 | Missing or invalid authentication | | `FORBIDDEN` | 403 | Insufficient permissions | | `NOT_FOUND` | 404 | Resource not found | | `VALIDATION_ERROR` | 422 | Request validation failed | | `RATE_LIMITED` | 429 | Too many requests | | `INTERNAL_ERROR` | 500 | Server error | --- ## OpenAPI Documentation Interactive API documentation is available at: - **Swagger UI:** `http://localhost:8000/docs` - **ReDoc:** `http://localhost:8000/redoc` --- _Last Updated: 2025-11-27_ 6:["slug","api-reference/rest-api","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","api-reference/rest-api","c"],{"children":["__PAGE__?{\"slug\":[\"api-reference\",\"rest-api\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","api-reference/rest-api","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"REST API Reference"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","api-reference/rest-api.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/api-reference/rest-api.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]] c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"REST API Reference | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Complete REST API documentation with request/response examples."}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]] 1:null