# Conversation Assistant API Reference Complete API documentation for the conversation-assistant feature. ## Server API (NestJS - Port 3100) ### Authentication All endpoints except `/api/devices/register` require JWT authentication. ``` Authorization: Bearer ``` --- ## Device Endpoints ### Register Device ```http POST /api/devices/register Content-Type: application/json { "name": "MacBook Pro", "hardwareId": "ABC123-DEF456", "platform": "macos", "osVersion": "14.0" } ``` **Response:** ```json { "deviceId": "uuid", "code": "123456", "expiresAt": "2024-01-01T00:10:00Z" } ``` ### Verify Device ```http POST /api/devices/verify Content-Type: application/json { "deviceId": "uuid", "code": "123456" } ``` **Response:** ```json { "token": "eyJhbGc...", "expiresAt": "2024-01-08T00:00:00Z" } ``` ### List Devices ```http GET /api/devices Authorization: Bearer ``` ### Deactivate Device ```http POST /api/devices/:id/deactivate Authorization: Bearer ``` --- ## Sync Endpoints ### Sync Messages ```http POST /api/sync/messages Authorization: Bearer Content-Type: application/json { "conversationImessageId": "iMessage-thread-id", "conversationDisplayName": "John Doe", "isGroup": false, "participantIds": ["contact-id-1"], "messages": [ { "imessageGuid": "msg-guid", "senderId": "contact-id-1", "direction": "incoming", "messageType": "text", "text": "Hello!", "sentAt": "2024-01-01T12:00:00Z" } ] } ``` ### Sync Contacts ```http POST /api/sync/contacts Authorization: Bearer Content-Type: application/json { "contacts": [ { "appleId": "john@icloud.com", "phoneNumber": "+1234567890", "email": "john@example.com", "displayName": "John Doe", "avatarHash": null } ] } ``` --- ## Conversation Endpoints ### List Conversations ```http GET /api/conversations?page=1&pageSize=20 Authorization: Bearer ``` **Response:** ```json { "conversations": [...], "total": 100, "page": 1, "pageSize": 20 } ``` ### Get Conversation Messages ```http GET /api/conversations/:id/messages?page=1&pageSize=50 Authorization: Bearer ``` --- ## Response Generation Endpoints ### Generate Response ```http POST /api/responses/generate Authorization: Bearer Content-Type: application/json { "messageId": "uuid", "context": { "maxHistory": 10, "includeContactInfo": true, "temperature": 0.7, "maxTokens": 256 } } ``` **Response:** ```json { "responseId": "uuid", "status": "completed", "response": "Generated text...", "confidence": 0.85, "modelVersion": "ministral-3b-instruct", "tokensUsed": 42 } ``` ### Response Action (Accept/Reject/Edit) ```http POST /api/responses/:id/action Authorization: Bearer Content-Type: application/json { "action": "accept" } ``` Or with edit: ```json { "action": "edit", "editedResponse": "Modified response text" } ``` Or with rejection: ```json { "action": "reject", "rejectionReason": "Too formal" } ``` --- ## Training Endpoints ### List Training Samples ```http GET /api/training/samples?page=1&pageSize=20 Authorization: Bearer ``` ### Start Training Job ```http POST /api/training/start Authorization: Bearer Content-Type: application/json { "baseModel": "ministral-3b-instruct", "epochs": 3, "learningRate": 0.0001, "sampleIds": ["uuid1", "uuid2"] } ``` ### Get Training Job Status ```http GET /api/training/jobs/:id Authorization: Bearer ``` **Response:** ```json { "job": { "id": "uuid", "status": "training", "progress": 45.0, "error": null } } ``` ### Cancel Training Job ```http POST /api/training/jobs/:id/cancel Authorization: Bearer ``` --- ## ML Service API (FastAPI - Port 8100) ### Health Check ```http GET /health ``` **Response:** ```json { "status": "healthy", "model_loaded": true, "model_version": "ministral-3b-instruct", "redis_connected": true, "queue_length": 0 } ``` ### Synchronous Generation ```http POST /generate Content-Type: application/json { "prompt": "Them: How are you?\nMe:", "max_tokens": 256, "temperature": 0.7, "top_p": 0.9, "repeat_penalty": 1.1, "stop": ["\nThem:", "\nMe:"], "cache_key": "optional-custom-key" } ``` **Response:** ```json { "response": "I'm doing great, thanks for asking!", "confidence": 0.82, "model_version": "ministral-3b-instruct", "tokens_used": 12, "cached": false } ``` ### Asynchronous Generation ```http POST /generate/async Content-Type: application/json { "prompt": "Them: What's your favorite color?\nMe:", "max_tokens": 256 } ``` **Response:** ```json { "job_id": "uuid", "status": "queued" } ``` ### Check Async Job Status ```http GET /generate/status/:job_id ``` **Response:** ```json { "job_id": "uuid", "status": "completed", "result": { "response": "I love blue!", "confidence": 0.78 }, "error": null, "created_at": "2024-01-01T12:00:00Z", "completed_at": "2024-01-01T12:00:02Z" } ``` ### Start Training ```http POST /training/start Content-Type: application/json { "job_id": "custom-job-id", "base_model": "ministral-3b-instruct", "samples": [ {"input": "How are you?", "output": "Great!", "quality": 1.0} ], "epochs": 3, "learning_rate": 0.0001 } ``` ### Get Training Status ```http GET /training/status/:job_id ``` ### Cancel Training ```http POST /training/cancel/:job_id ``` ### Reload Model ```http POST /model/reload?model_id=new-model-id ``` ### Clear Cache ```http DELETE /cache?pattern=* ``` **Response:** ```json { "invalidated": 42 } ``` --- ## Error Responses All endpoints return errors in this format: ```json { "statusCode": 400, "message": "Error description", "error": "Bad Request" } ``` Common status codes: - `400` - Bad request (validation error) - `401` - Unauthorized (missing/invalid token) - `403` - Forbidden (device not authorized) - `404` - Not found - `409` - Conflict (e.g., job ID already exists) - `503` - Service unavailable (model not loaded, Redis down) --- ## Rate Limiting - Device verification: 5 attempts per 15 minutes - Generation: No limit (but queue-based) - Training: 1 concurrent job per device --- ## WebSocket Events (Future) Planned real-time events for: - `response:generating` - Generation started - `response:completed` - Response ready - `training:progress` - Training progress updates