API Reference
Technical API specification for SophieAI platform
API Reference
Complete technical specification for the SophieAI educational platform API.
API Version: v1.0.0 | OpenAPI Spec: Available at /docs when ENABLE_SWAGGER=true
Base Configuration
Base URL: http://localhost:5000 (development)
Protocol: HTTP/1.1, HTTP/2
Content-Type: application/json (default) | multipart/form-data (file uploads)
CORS: Enabled for http://localhost:3000
Base URL: https://your-domain.com
Protocol: HTTPS only
Content-Type: application/json (default) | multipart/form-data (file uploads)
CORS: Configure for your production domain
Security: Always use HTTPS in production and configure proper CORS origins for security.
Required Headers:
Content-Type: application/json
Cookie: authjs.session-token=<session-token>Optional Headers:
X-Requested-With: XMLHttpRequest
Accept: application/jsonAuthentication
Method: Session-based authentication with Better-auth
Session Management: Cookie-based sessions
Session Duration: Persistent until logout
Authentication Flow
Sign In: Use email/password or Google OAuth
curl -X POST http://localhost:5000/api/auth/signin \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}'Receive Session Cookie: Authentication sets httpOnly session cookie
Make Authenticated Requests: Cookie automatically included in subsequent requests
Authentication Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/auth/signin | POST | User authentication (email/password) |
/api/auth/signin/google | GET | Google OAuth authentication |
/api/auth/signup | POST | User registration |
/api/auth/signout | POST | Session termination |
/api/auth/session | GET | Session validation |
/api/auth/callback/google | GET | Google OAuth callback |
Response Formats
Standard Success Response:
{
"success": true,
"data": {},
"message": "string"
}Example:
{
"success": true,
"data": {
"id": "course_123",
"name": "Mathematics 101",
"professor": "Dr. Smith"
},
"message": "Course created successfully"
}Error Response Format:
{
"success": false,
"error": "string",
"code": "ERROR_CODE",
"details": []
}Example:
{
"success": false,
"error": "Invalid email format",
"code": "VALIDATION_ERROR",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
]
}Background Job Response:
{
"success": true,
"data": {
"importJob": {
"id": "string",
"status": "pending|processing|completed|failed",
"progress": 0,
"createdAt": "ISO8601"
}
}
}Job Polling: Use the job ID with /api/jobs/:id to check processing status and progress.
Paginated Response:
{
"success": true,
"data": [],
"pagination": {
"limit": 20,
"offset": 0,
"total": 157,
"hasMore": true
}
}Query Parameters:
limit: Items per page (1-100, default: 20)offset: Items to skip (default: 0)search: Search query string
HTTP Status Codes
| Code | Usage | Description |
|---|---|---|
| 200 | Success | Standard successful response |
| 201 | Created | Resource created successfully |
| 204 | No Content | Successful request with no response body |
| Code | Usage | Description |
|---|---|---|
| 400 | Bad Request | Invalid request format/data |
| 401 | Unauthorized | Authentication required/failed |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Resource already exists |
| 413 | Payload Too Large | File size exceeded |
| 422 | Unprocessable Entity | Validation errors |
| Code | Usage | Description |
|---|---|---|
| 500 | Internal Error | Server processing error |
| 502 | Bad Gateway | Upstream service error |
| 503 | Service Unavailable | Temporary service outage |
| 504 | Gateway Timeout | Upstream service timeout |
File Upload Specifications
File Size Limits: Maximum file size is 150MB. Connection timeout is 5 minutes, request timeout is 10 minutes.
Content-Type
multipart/form-data
Supported File Types
Supported Formats:
- PDF, DOC, DOCX
- PPT, PPTX
- XLS, XLSX
- TXT
Processing Features:
- Text extraction
- Metadata parsing
- Content analysis
- Semantic search indexing
Supported Formats:
- MP3, WAV, M4A
- AAC, OGG, FLAC
- WEBM
Processing Features:
- Audio transcription
- Speaker diarization
- Noise reduction
- Format conversion
Supported Formats:
- MP4, MOV, AVI
- MKV, WEBM
Processing Features:
- Audio extraction
- Video transcription
- Thumbnail generation
- Format conversion
Upload Response Format
{
"success": true,
"data": {
"id": "string",
"title": "string",
"fileUrl": "string",
"fileSize": "number",
"mimeType": "string",
"status": "pending|processing|completed|failed"
}
}API Endpoints Overview
Core Resources
| Resource | Base Path | Description |
|---|---|---|
| Authentication | /api/auth/* | User authentication and session management |
| Courses | /api/courses | Course management |
| Notes | /api/notes | Note creation, transcription, and management |
| Documents | /api/documents/* | Document upload, processing, and search |
| Flashcards | /api/flashcards | Flashcard set management |
| Quizzes | /api/quizzes | Quiz creation and management |
| Study Guides | /api/study-guides | Study guide generation |
| Chat | /api/chat | AI chat sessions |
| Calendar | /api/calendar | Calendar events and management |
| Jobs | /api/jobs | Background job status tracking |
| Search | /api/search | Universal search across content |
| Dashboard | /api/dashboard | Dashboard statistics |
| Notifications | /api/notifications | User notifications |
| Apple iOS | /api/apple/* | Apple subscriptions (ASSN v2, confirm purchase) |
System Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/health | GET | Health check |
/docs | GET | Swagger documentation (when enabled) |
/ | GET | Redirects to client application |
Error Handling
| Code | Description |
|---|---|
UNAUTHORIZED | Authentication required |
FORBIDDEN | Insufficient permissions |
NOT_FOUND | Resource not found |
VALIDATION_ERROR | Request validation failed |
DATABASE_TIMEOUT | Database operation timeout |
INTERNAL_ERROR | Unexpected server error |
| Code | Description |
|---|---|
FILE_TOO_LARGE | File exceeds size limit |
CONNECTION_TIMEOUT | Upload connection interrupted |
UNEXPECTED_FILE | Unsupported file format |
UPLOAD_INTERRUPTED | File upload was interrupted |
| Code | Description |
|---|---|
INVALID_CREDENTIALS | Email/password incorrect |
SESSION_EXPIRED | Session has expired |
OAUTH_ERROR | Google OAuth error |
ACCOUNT_LOCKED | Account temporarily locked |
Rate Limiting
Current Status: No specific rate limiting implemented. File upload limits enforced by server configuration. Connection timeouts prevent resource exhaustion.
Recommended Limits for Production:
- API requests: 1000 requests per hour per user
- File uploads: 10 uploads per hour per user
- AI generation: 50 requests per hour per user
Quick Start Examples
// Authenticate first
const authResponse = await fetch('/api/auth/signin', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'user@example.com',
password: 'password'
}),
credentials: 'include' // Include cookies
});
// Make authenticated request
const coursesResponse = await fetch('/api/courses', {
credentials: 'include' // Include session cookie
});
const courses = await coursesResponse.json();# Sign in and save cookies
curl -c cookies.txt -X POST http://localhost:5000/api/auth/signin \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}'
# Use cookies for authenticated requests
curl -b cookies.txt http://localhost:5000/api/courses
# Upload a file
curl -b cookies.txt -X POST http://localhost:5000/api/documents/upload \
-F "file=@document.pdf" \
-F "title=Course Material"import requests
# Create session to persist cookies
session = requests.Session()
# Authenticate
auth_response = session.post('http://localhost:5000/api/auth/signin',
json={'email': 'user@example.com', 'password': 'password'})
# Make authenticated requests
courses_response = session.get('http://localhost:5000/api/courses')
courses = courses_response.json()
# Upload file
with open('document.pdf', 'rb') as f:
upload_response = session.post('http://localhost:5000/api/documents/upload',
files={'file': f},
data={'title': 'Course Material'})Ready to explore? Check out our specific API guides for detailed endpoint documentation and examples.