TellaAI
API Reference

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/json

Authentication

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

EndpointMethodPurpose
/api/auth/signinPOSTUser authentication (email/password)
/api/auth/signin/googleGETGoogle OAuth authentication
/api/auth/signupPOSTUser registration
/api/auth/signoutPOSTSession termination
/api/auth/sessionGETSession validation
/api/auth/callback/googleGETGoogle 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

CodeUsageDescription
200SuccessStandard successful response
201CreatedResource created successfully
204No ContentSuccessful request with no response body
CodeUsageDescription
400Bad RequestInvalid request format/data
401UnauthorizedAuthentication required/failed
403ForbiddenInsufficient permissions
404Not FoundResource does not exist
409ConflictResource already exists
413Payload Too LargeFile size exceeded
422Unprocessable EntityValidation errors
CodeUsageDescription
500Internal ErrorServer processing error
502Bad GatewayUpstream service error
503Service UnavailableTemporary service outage
504Gateway TimeoutUpstream 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

Upload Response
{
  "success": true,
  "data": {
    "id": "string",
    "title": "string",
    "fileUrl": "string",
    "fileSize": "number",
    "mimeType": "string",
    "status": "pending|processing|completed|failed"
  }
}

API Endpoints Overview

Core Resources

ResourceBase PathDescription
Authentication/api/auth/*User authentication and session management
Courses/api/coursesCourse management
Notes/api/notesNote creation, transcription, and management
Documents/api/documents/*Document upload, processing, and search
Flashcards/api/flashcardsFlashcard set management
Quizzes/api/quizzesQuiz creation and management
Study Guides/api/study-guidesStudy guide generation
Chat/api/chatAI chat sessions
Calendar/api/calendarCalendar events and management
Jobs/api/jobsBackground job status tracking
Search/api/searchUniversal search across content
Dashboard/api/dashboardDashboard statistics
Notifications/api/notificationsUser notifications
Apple iOS/api/apple/*Apple subscriptions (ASSN v2, confirm purchase)

System Endpoints

EndpointMethodPurpose
/healthGETHealth check
/docsGETSwagger documentation (when enabled)
/GETRedirects to client application

Error Handling

CodeDescription
UNAUTHORIZEDAuthentication required
FORBIDDENInsufficient permissions
NOT_FOUNDResource not found
VALIDATION_ERRORRequest validation failed
DATABASE_TIMEOUTDatabase operation timeout
INTERNAL_ERRORUnexpected server error
CodeDescription
FILE_TOO_LARGEFile exceeds size limit
CONNECTION_TIMEOUTUpload connection interrupted
UNEXPECTED_FILEUnsupported file format
UPLOAD_INTERRUPTEDFile upload was interrupted
CodeDescription
INVALID_CREDENTIALSEmail/password incorrect
SESSION_EXPIREDSession has expired
OAUTH_ERRORGoogle OAuth error
ACCOUNT_LOCKEDAccount 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

Basic API Request
// 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();
cURL Examples
# 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"
Python Requests
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.