API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The ClassMate API Reference provides a comprehensive guide to the RESTful and WebSocket endpoints that power the AI-driven meeting assistant. The API is divided into several functional domains: a Public API for external integrations and general session management, an AI Agent API for educational tools (Q&A, flashcards, quizzes), and core security/authentication services.
The system utilizes a FastAPI-based backend that interacts with Celery workers for heavy lifting (transcription and note generation) and a Vector Memory Store for semantic searches.
Sources: PROJECT_STRUCTURE.md:120-130, ai_backend/api/public_api.py:1-25
Authentication and Security
Security is managed through a combination of Firebase Authentication for user identity and custom API key management for third-party integrations. All sensitive endpoints require a valid bearer token or API key.
Security Layers
The API implements several middleware layers to ensure system integrity:
- Rate Limiting: Per-IP limits are enforced to prevent abuse, with specific tiers for authentication and AI endpoints.
- Request Validation: Suspicious patterns (e.g., SQL injection, XSS) are blocked via regex matching.
- Security Headers: Headers like
X-Content-Type-Options,X-Frame-Options, and CSP are applied to all responses.
Sources: ai_backend/core/security.py:32-75, ai_backend/core/security.py:126-160
This diagram illustrates the sequence of security checks applied to every incoming API request.
API Key Management
For external tools, the APIKeyManager handles the lifecycle of cm-prefixed keys.
| Component | Description |
|---|---|
generate_api_key | Creates a new key with specific permissions and 365-day expiry. |
validate_api_key | Verifies the key hash and salt, checks rate limits, and updates usage stats. |
_check_rate_limit | Implements a sliding-window limit (default 1000 req/hour per IP). |
Sources: ai_backend/api/public_api.py:27-110
AI Agent API
The AI Agent API (/api/v1/ai) provides intelligent interaction with session data. It leverages StudyAssistantAgent to process transcripts and generate educational content.
Study Assistance Endpoints
| Endpoint | Method | Purpose | Key Parameters |
|---|---|---|---|
/ask | POST | Ask questions about content. | question, session_id |
/flashcards | POST | Generate study cards. | transcript, count |
/quiz | POST | Create MCQ practice tests. | question_count, difficulty |
/explain | POST | Simplify complex concepts. | concept, style |
/index | POST | Store content in vector DB. | content, content_type |
Sources: ai_backend/api/ai_agent_api.py:45-120
Semantic Search and Vector Memory
The API supports semantic search across indexed content. It converts queries into embeddings to find relevant segments within transcripts or summaries.
The search flow highlights the retrieval-augmented generation (RAG) capabilities of the AI Agent.
Public API and Session Management
The Public API (/api/v1/public) handles the core lifecycle of meeting recordings and data retrieval.
Session Operations
- Listing Sessions: Supports pagination (
limit,offset) and filtering byuser_id. - Retrieving Transcripts: Fetches full text along with structured chunks containing speaker IDs and confidence scores.
- Health Checks: A dedicated
/healthendpoint provides status, versioning, and a directory of available public endpoints.
Sources: ai_backend/api/public_api.py:202-280, ai_backend/api/public_api.py:338-350
Real-time Transcription (WebSocket)
The web application communicates via a WebSocket protocol for live audio streaming and instantaneous transcription results.
| Message Type | Direction | Description |
|---|---|---|
audio_chunk | Client -> Server | Base64 encoded audio data with chunk index. |
transcription_result | Server -> Client | Partial transcript text with speaker and timestamp. |
get_transcript | Client -> Server | Request for the final processed session transcript. |
Sources: web_app/src/main.js:145-180, web_app/src/main.js:215-240
This diagram represents the real-time data flow between the client and the transcription pipeline.
Sources: web_app/src/main.js:256-270
Data Models
Request Structures
// QuizRequest
{
"session_id": "string",
"transcript": "string",
"question_count": 5,
"difficulty": "medium"
}
Sources: ai_backend/api/ai_agent_api.py:34-39
API Statistics
The /stats endpoint returns usage metrics for the AI features.
- indexed_documents: Count of documents stored in vector memory.
- vector_db: Indicator of whether
pgvectoror keyword fallback is in use. - ai_features: List of enabled capabilities (e.g.,
explain,semantic_search).
Sources: ai_backend/api/ai_agent_api.py:153-170
Conclusion
The API Reference provides the technical foundation for interacting with the ClassMate backend. By combining secure RESTful endpoints for session management with high-performance WebSockets for real-time transcription and a specialized AI Agent API for educational tasks, the system enables a robust, scalable meeting assistance experience. Developers should prioritize the use of the APIKeyManager for external integrations and adhere to the rate limits defined in the security core.