TellaAI
API Reference/Core Content

Notes API

Note creation, import, and audio transcription endpoints

Notes API

The Notes API allows users to create, import, and manage academic notes with automatic transcription capabilities. Supports importing from YouTube videos, audio URLs, and direct audio file uploads with AI-powered transcription and content processing.

Note Model

  • id: Unique note identifier (string)
  • title: Note title (string)
  • content: Note content/transcript (string, optional)
  • courseId: Associated course ID (string)
  • audioUrl: URL to audio file (string, optional)
  • transcriptionStatus: Transcription processing status (string: "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED")
  • metadata: Additional note metadata (object, optional)
  • createdAt: ISO datetime when created (string)
  • updatedAt: ISO datetime when last updated (string)
  • userId: Owner user ID (string)
  • transcriptSegments: Array of transcript segment objects (optional)

Transcript Segment Model

  • id: Unique segment identifier (string)
  • text: Transcript text for this segment (string)
  • startTime: Segment start time in seconds (number)
  • endTime: Segment end time in seconds (number)
  • speaker: Speaker identifier (string, optional)
  • noteId: Parent note ID (string)

Endpoints

All note endpoints require authentication and are scoped to the authenticated user.

Get All Notes

Retrieve all notes for the authenticated user across all courses.

GET /api/notes

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "note_abc123",
      "title": "Biology Lecture: Cell Structure and Function",
      "content": "Today we'll be discussing the fundamental structures of cells. Cells are the basic units of life...",
      "courseId": "course_abc123",
      "course": {
        "id": "course_abc123",
        "name": "Biology 101",
        "color": "green",
        "emoji": "🧬"
      },
      "audioUrl": "https://storage.example.com/audio/note_abc123.mp3",
      "transcriptionStatus": "COMPLETED",
      "metadata": {
        "source": "youtube",
        "originalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "duration": 1800,
        "wordCount": 2500
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T01:00:00.000Z",
      "userId": "user_123"
    },
    {
      "id": "note_def456",
      "title": "Physics Lecture: Quantum Mechanics",
      "content": "In this lecture, we explore fundamental quantum principles...",
      "courseId": "course_xyz789",
      "course": {
        "id": "course_xyz789",
        "name": "Physics 301",
        "color": "blue",
        "emoji": "⚛️"
      },
      "audioUrl": "https://storage.example.com/audio/note_def456.mp3",
      "transcriptionStatus": "COMPLETED",
      "metadata": {
        "source": "audio_url",
        "duration": 2100,
        "wordCount": 3200
      },
      "createdAt": "2024-01-01T02:00:00.000Z",
      "updatedAt": "2024-01-01T03:00:00.000Z",
      "userId": "user_123"
    }
  ],
  "message": "All notes retrieved successfully"
}

Errors:

  • 401: Authentication required

Import from YouTube

Import audio from a YouTube video, transcribe it, and create a note with auto-generated title.

POST /api/notes/import/youtube
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "courseId": "course_abc123",
  "speedMultiplier": 2
}

Request Body Parameters

  • url: YouTube video URL (required, valid URL format)
  • courseId: ID of the course to add the note to (required, string)
  • speedMultiplier: Transcription speed multiplier (optional, number: 1 or 2, default: 2)
    • 1: Standard 1x speed transcription
    • 2: Cost-optimized 2x speed transcription (saves ~50% on costs)

Response (201)

{
  "success": true,
  "data": {
    "note": {
      "id": "note_abc123",
      "title": "Biology Lecture: Cell Structure and Function",
      "content": null,
      "courseId": "course_abc123",
      "audioUrl": "https://storage.example.com/audio/note_abc123.mp3",
      "transcriptionStatus": "PENDING",
      "metadata": {
        "source": "youtube",
        "originalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "duration": 1800
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123"
    },
    "importJob": {
      "id": "job_abc123",
      "status": "PENDING",
      "type": "youtube_import",
      "noteId": "note_abc123"
    },
    "videoInfo": {
      "title": "Biology Lecture: Cell Structure and Function",
      "duration": 1800,
      "description": "Introduction to cellular biology concepts",
      "uploader": "BiologyProfessor"
    }
  },
  "message": "YouTube import started successfully"
}

Errors:

  • 400: Invalid YouTube URL or validation errors
  • 401: Authentication required
  • 404: Course not found

Import from Audio URL

Import audio from a direct URL, transcribe it, and create a note with auto-generated title.

POST /api/notes/import/audio
Content-Type: application/json

{
  "url": "https://example.com/audio/lecture.mp3",
  "courseId": "course_abc123",
  "mimeType": "audio/mpeg",
  "speedMultiplier": 2
}

Request Body Parameters

  • url: Direct URL to audio file (required, valid URL format)
  • courseId: ID of the course to add the note to (required, string)
  • mimeType: MIME type of the audio file (optional, string)
  • speedMultiplier: Transcription speed multiplier (optional, number: 1 or 2, default: 2)
    • 1: Standard 1x speed transcription
    • 2: Cost-optimized 2x speed transcription (saves ~50% on costs)

Supported Audio Formats

  • MP3: audio/mpeg
  • WAV: audio/wav
  • M4A: audio/m4a
  • AAC: audio/aac
  • OGG: audio/ogg
  • FLAC: audio/flac
  • WEBM: audio/webm
  • MP4: video/mp4 (audio extraction)

Response (201)

{
  "success": true,
  "data": {
    "note": {
      "id": "note_def456",
      "title": "Imported Audio: lecture.mp3",
      "content": null,
      "courseId": "course_abc123",
      "audioUrl": "https://storage.example.com/audio/note_def456.mp3",
      "transcriptionStatus": "PENDING",
      "metadata": {
        "source": "audio_url",
        "originalUrl": "https://example.com/audio/lecture.mp3",
        "mimeType": "audio/mpeg"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123"
    },
    "importJob": {
      "id": "job_def456",
      "status": "PENDING",
      "type": "audio_import",
      "noteId": "note_def456"
    }
  },
  "message": "Audio import started successfully"
}

Errors:

  • 400: Invalid audio URL or unsupported format
  • 401: Authentication required
  • 404: Course not found

Upload Audio File

Upload an audio file directly, store it, and create a note with transcription processing.

POST /api/notes/upload/audio
Content-Type: multipart/form-data

# Form data:
file: [binary audio file]
courseId: "course_abc123"
title: "Lecture Recording - Chapter 1"
speedMultiplier: 2

Request Body (Multipart Form Data)

  • file: Audio file to upload (required, max 150MB)
  • courseId: ID of the course to add the note to (required, string)
  • title: Custom title for the note (optional, defaults to filename)
  • speedMultiplier: Transcription speed multiplier (optional, number: 1 or 2, default: 2)
    • 1: Standard 1x speed transcription
    • 2: Cost-optimized 2x speed transcription (saves ~50% on costs)

File Size and Format Limits

  • Maximum file size: 150MB
  • Supported formats: MP3, WAV, M4A, AAC, OGG, FLAC, WEBM, MP4
  • Recommended format: MP3 or WAV for best compatibility
  • Quality recommendations: 44.1kHz sample rate, 16-bit depth minimum

Response (201)

{
  "success": true,
  "data": {
    "note": {
      "id": "note_ghi789",
      "title": "Lecture Recording - Chapter 1",
      "content": null,
      "courseId": "course_abc123",
      "audioUrl": "https://storage.example.com/audio/note_ghi789.mp3",
      "transcriptionStatus": "PENDING",
      "metadata": {
        "source": "upload",
        "originalFilename": "lecture_ch1.mp3",
        "fileSize": 25600000,
        "duration": 2400
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123"
    },
    "importJob": {
      "id": "job_ghi789",
      "status": "PENDING",
      "type": "audio_upload",
      "noteId": "note_ghi789"
    },
    "uploadInfo": {
      "filename": "lecture_ch1.mp3",
      "size": 25600000,
      "mimeType": "audio/mpeg",
      "s3Key": "audio/user_123/note_ghi789.mp3"
    }
  },
  "message": "Audio file uploaded successfully"
}

Errors:

  • 400: Invalid file format, file too large, or missing course ID
  • 401: Authentication required

Get Notes by Course

Retrieve all notes for a specific course.

GET /api/courses/{courseId}/notes

Path Parameters

  • courseId: Course ID to retrieve notes for (required, string)

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "note_abc123",
      "title": "Biology Lecture: Cell Structure and Function",
      "content": "Today we'll be discussing the fundamental structures of cells. Cells are the basic units of life...",
      "courseId": "course_abc123",
      "audioUrl": "https://storage.example.com/audio/note_abc123.mp3",
      "transcriptionStatus": "COMPLETED",
      "metadata": {
        "source": "youtube",
        "originalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "duration": 1800,
        "wordCount": 2500
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T01:00:00.000Z",
      "userId": "user_123"
    },
    {
      "id": "note_def456",
      "title": "Imported Audio: lecture.mp3",
      "content": "In this lecture, we explore cellular organelles and their functions...",
      "courseId": "course_abc123",
      "audioUrl": "https://storage.example.com/audio/note_def456.mp3",
      "transcriptionStatus": "COMPLETED",
      "metadata": {
        "source": "audio_url",
        "duration": 2100,
        "wordCount": 3200
      },
      "createdAt": "2024-01-01T02:00:00.000Z",
      "updatedAt": "2024-01-01T03:00:00.000Z",
      "userId": "user_123"
    }
  ],
  "message": "Notes retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Course not found

Get Note by ID

Retrieve a specific note with transcript segments and course information.

GET /api/notes/{id}

Path Parameters

  • id: Note ID to retrieve (required, string)

Response (200)

{
  "success": true,
  "data": {
    "id": "note_abc123",
    "title": "Biology Lecture: Cell Structure and Function",
    "content": "Today we'll be discussing the fundamental structures of cells. Cells are the basic units of life...",
    "courseId": "course_abc123",
    "audioUrl": "https://storage.example.com/audio/note_abc123.mp3",
    "transcriptionStatus": "COMPLETED",
    "metadata": {
      "source": "youtube",
      "originalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "duration": 1800,
      "wordCount": 2500,
      "language": "en",
      "confidence": 0.92
    },
    "transcriptSegments": [
      {
        "id": "segment_abc123",
        "text": "Today we'll be discussing the fundamental structures of cells.",
        "startTime": 0.0,
        "endTime": 4.2,
        "speaker": "instructor",
        "noteId": "note_abc123"
      },
      {
        "id": "segment_def456",
        "text": "Cells are the basic units of life and contain various organelles.",
        "startTime": 4.2,
        "endTime": 8.7,
        "speaker": "instructor",
        "noteId": "note_abc123"
      }
    ],
    "course": {
      "id": "course_abc123",
      "name": "Biology 101",
      "professor": "Dr. Sarah Wilson",
      "semester": "Spring 2024"
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T01:00:00.000Z",
    "userId": "user_123"
  },
  "message": "Note retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Note not found

Update User Manual Notes

Add, edit, or remove manual annotations and notes for a specific note with timestamp references.

PUT /api/notes/{id}/user-notes
Content-Type: application/json

{
  "userNotes": [
    {
      "timestamp": 120.5,
      "content": "Important concept: Cell membrane structure",
      "contentType": "text"
    },
    {
      "timestamp": 245.0,
      "content": "https://example.com/cell-diagram.png",
      "contentType": "url"
    },
    {
      "timestamp": 380.2,
      "content": "Review this section for exam",
      "contentType": "text"
    }
  ]
}

Path Parameters

  • id: Note ID to update user notes for (required, string)

Request Body Parameters

  • userNotes: Array of user note objects (required, array)
    • timestamp: Time position in seconds where note applies (required, number ≥ 0)
    • content: Note content - text annotation or URL reference (required, string, min length: 1)
    • contentType: Type of content (required, string: "text" | "url" | "file")
      • "text": Plain text annotation or comment
      • "url": URL reference to external resource
      • "file": File attachment (image, document, etc.)

User Notes Features

  • Timestamp-based: Each note is anchored to a specific time in the audio
  • Mixed Content: Support both text annotations and URL references
  • Automatic Sorting: Notes are automatically sorted by timestamp
  • Real-time Sync: Updates are saved immediately and synced across devices
  • Audio Navigation: Click on notes to jump to specific audio positions

Response (200)

{
  "success": true,
  "data": {
    "id": "note_abc123",
    "title": "Biology Lecture: Cell Structure and Function",
    "content": "Today we'll be discussing the fundamental structures of cells...",
    "courseId": "course_abc123",
    "userNotes": [
      {
        "timestamp": 120.5,
        "content": "Important concept: Cell membrane structure",
        "contentType": "text"
      },
      {
        "timestamp": 245.0,
        "content": "https://example.com/cell-diagram.png",
        "contentType": "url"
      },
      {
        "timestamp": 380.2,
        "content": "Review this section for exam",
        "contentType": "text"
      }
    ],
    "audioUrl": "https://storage.example.com/audio/note_abc123.mp3",
    "transcriptionStatus": "COMPLETED",
    "updatedAt": "2024-01-01T12:30:00.000Z",
    "userId": "user_123"
  },
  "message": "User notes updated successfully"
}

Errors:

  • 400: Invalid request body or validation errors
  • 401: Authentication required
  • 404: Note not found
  • 500: Failed to update user notes

Upload File Attachment for User Notes

Upload a file to be attached to a user manual note with timestamp reference.

POST /api/notes/{id}/attachments
Content-Type: multipart/form-data

# Form data:
file: [binary file]
timestamp: 180.5
description: "Cell structure diagram"

Path Parameters

  • id: Note ID to upload attachment for (required, string)

Request Body (Multipart Form Data)

  • file: File to upload (required, max size varies by type)
  • timestamp: Time position in seconds where file applies (required, number ≥ 0)
  • description: Optional description of the file (optional, string)

Supported File Types and Limits

  • Images: PNG, JPG, JPEG, GIF, WebP (max 10MB each)
  • Documents: PDF, DOC, DOCX, TXT (max 25MB each)
  • Presentations: PPT, PPTX (max 25MB each)
  • Spreadsheets: XLS, XLSX, CSV (max 10MB each)

Response (201)

{
  "success": true,
  "data": {
    "fileUrl": "https://storage.example.com/attachments/user_123/note_abc123/diagram_180.png",
    "fileName": "cell-structure-diagram.png",
    "fileSize": 2048000,
    "mimeType": "image/png",
    "timestamp": 180.5,
    "description": "Cell structure diagram",
    "uploadedAt": "2024-01-01T12:30:00.000Z"
  },
  "message": "File attachment uploaded successfully"
}

Usage with User Notes

After uploading, use the returned fileUrl in your user notes:

{
  "userNotes": [
    {
      "timestamp": 180.5,
      "content": "https://storage.example.com/attachments/user_123/note_abc123/diagram_180.png",
      "contentType": "file"
    }
  ]
}

Errors:

  • 400: Invalid file type, file too large, or missing timestamp
  • 401: Authentication required
  • 404: Note not found
  • 413: File size exceeds limit

User Manual Notes Model

User notes are stored as an array of objects with the following structure:

  • timestamp: Time position in audio (number, seconds from start)
  • content: Note content (string, 1-1000 characters)
  • contentType: Content type (string: "text" | "url" | "file")

Content Types

Text Notes

{
  "timestamp": 120.5,
  "content": "Key concept to remember for exam",
  "contentType": "text"
}

URL References

{
  "timestamp": 245.0,
  "content": "https://example.com/supplementary-material.pdf",
  "contentType": "url"
}

File Attachments

{
  "timestamp": 180.0,
  "content": "https://storage.example.com/attachments/user_123/diagram.png",
  "contentType": "file"
}

File Attachment Support

User manual notes support file attachments for enhanced learning materials:

Supported File Types

  • Images: PNG, JPG, JPEG, GIF, WebP (max 10MB each)
  • Documents: PDF, DOC, DOCX, TXT (max 25MB each)
  • Presentations: PPT, PPTX (max 25MB each)
  • Spreadsheets: XLS, XLSX, CSV (max 10MB each)

File Upload Process

  1. Upload file via separate endpoint: POST /api/notes/{id}/attachments
  2. Receive file URL in response
  3. Add file URL to user note with contentType: "file"

File Storage

  • Files are securely stored in cloud storage
  • Automatic virus scanning and validation
  • CDN delivery for fast access
  • User-scoped access control

Usage Patterns

  • Study Annotations: Mark important concepts and definitions
  • Exam Preparation: Flag sections to review before tests
  • Resource Links: Reference external materials and diagrams
  • File Attachments: Upload images, documents, and study materials
  • Personal Reminders: Add context-specific notes and thoughts
  • Collaboration: Share timestamped insights with study groups

Usage Examples

Import from YouTube

// Import a lecture from YouTube with 2x speed transcription (default)
const response = await fetch('/api/notes/import/youtube', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    courseId: 'course_abc123',
    speedMultiplier: 2  // Optional: 1 for 1x speed, 2 for 2x speed (default)
  })
});

const result = await response.json();
console.log('Import started:', result.data.note.id);
console.log('Job ID:', result.data.importJob.id);

// For slower, more accurate transcription use 1x speed
const slowResponse = await fetch('/api/notes/import/youtube', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=another-video',
    courseId: 'course_abc123',
    speedMultiplier: 1  // Use 1x speed for maximum accuracy
  })
});

// Check transcription status later
const noteResponse = await fetch(`/api/notes/${result.data.note.id}`, {
  headers: { 'Authorization': 'Bearer your-token' }
});
const note = await noteResponse.json();
console.log('Transcription status:', note.data.transcriptionStatus);

Upload Audio File

// Upload an audio file with 2x speed transcription (default)
const formData = new FormData();
formData.append('file', audioFileInput.files[0]);
formData.append('courseId', 'course_abc123');
formData.append('title', 'Recorded Lecture - Mitosis');
formData.append('speedMultiplier', '2'); // Optional: 1 or 2 (default: 2)

const response = await fetch('/api/notes/upload/audio', {
  method: 'POST',
  body: formData,
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const result = await response.json();
console.log('Upload successful:', result.data.note.title);
console.log('Processing job:', result.data.importJob.id);

// For higher accuracy, use 1x speed
const accurateFormData = new FormData();
accurateFormData.append('file', importantAudioFile);
accurateFormData.append('courseId', 'course_abc123');
accurateFormData.append('title', 'Important Exam Review');
accurateFormData.append('speedMultiplier', '1'); // Use 1x for maximum accuracy

const accurateResponse = await fetch('/api/notes/upload/audio', {
  method: 'POST',
  body: accurateFormData,
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

Get All Notes Across Courses

// Get all notes across all courses
const response = await fetch('/api/notes', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const result = await response.json();
console.log(`Found ${result.data.length} notes across all courses`);

// Display notes grouped by course
const notesByCourse = {};
result.data.forEach(note => {
  const courseName = note.course?.name || 'Unknown Course';
  if (!notesByCourse[courseName]) {
    notesByCourse[courseName] = [];
  }
  notesByCourse[courseName].push(note);
});

// Log notes by course
Object.entries(notesByCourse).forEach(([courseName, courseNotes]) => {
  console.log(`${courseName}: ${courseNotes.length} notes`);
  courseNotes.forEach(note => {
    console.log(`- ${note.title} (${note.transcriptionStatus})`);
  });
});

Get Course Notes

// Get all notes for a course
const response = await fetch('/api/courses/course_abc123/notes', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const notes = await response.json();
console.log(`Found ${notes.data.length} notes for course`);

notes.data.forEach(note => {
  console.log(`${note.title} - Status: ${note.transcriptionStatus}`);
});

Access Transcript Segments

// Get detailed note with transcript segments
const response = await fetch('/api/notes/note_abc123', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const note = await response.json();
console.log('Note:', note.data.title);
console.log('Full transcript:', note.data.content);

// Access individual segments for precise timing
note.data.transcriptSegments.forEach((segment, index) => {
  console.log(`[${segment.startTime}s - ${segment.endTime}s]: ${segment.text}`);
});

Manage User Manual Notes

// Add manual notes to a lecture
const userNotes = [
  {
    timestamp: 120.5,
    content: "Important concept: Cell membrane structure",
    contentType: "text"
  },
  {
    timestamp: 245.0,
    content: "https://example.com/cell-diagram.png",
    contentType: "url"
  },
  {
    timestamp: 380.2,
    content: "Review this section for exam",
    contentType: "text"
  }
];

const response = await fetch('/api/notes/note_abc123/user-notes', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({ userNotes })
});

const result = await response.json();
console.log('User notes updated:', result.data.userNotes.length);

// Get note with user notes included
const noteResponse = await fetch('/api/notes/note_abc123', {
  headers: { 'Authorization': 'Bearer your-token' }
});

const noteData = await noteResponse.json();
console.log('Note with user annotations:', noteData.data.title);

// Display user notes sorted by timestamp
noteData.data.userNotes.forEach(note => {
  const timeFormatted = `${Math.floor(note.timestamp / 60)}:${(note.timestamp % 60).toFixed(1).padStart(4, '0')}`;
  console.log(`[${timeFormatted}] ${note.content} (${note.contentType})`);
});

// Example: Add a new note while preserving existing ones
const existingNotes = noteData.data.userNotes || [];
const newNote = {
  timestamp: 450.0,
  content: "Question: How does osmosis work?",
  contentType: "text"
};

const updatedNotes = [...existingNotes, newNote].sort((a, b) => a.timestamp - b.timestamp);

await fetch('/api/notes/note_abc123/user-notes', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({ userNotes: updatedNotes })
});

// Example: Remove a specific note by timestamp
const filteredNotes = existingNotes.filter(note => note.timestamp !== 245.0);

await fetch('/api/notes/note_abc123/user-notes', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({ userNotes: filteredNotes })
});

Upload File Attachments for User Notes

// Upload a file attachment for a specific timestamp
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];

const formData = new FormData();
formData.append('file', file);
formData.append('timestamp', '180.5');
formData.append('description', 'Cell structure diagram');

const uploadResponse = await fetch('/api/notes/note_abc123/attachments', {
  method: 'POST',
  body: formData,
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const uploadResult = await uploadResponse.json();
console.log('File uploaded:', uploadResult.data.fileName);

// Now add the file URL to user notes
const existingNotes = noteData.data.userNotes || [];
const fileNote = {
  timestamp: 180.5,
  content: uploadResult.data.fileUrl,
  contentType: "file"
};

const updatedNotesWithFile = [...existingNotes, fileNote].sort((a, b) => a.timestamp - b.timestamp);

await fetch('/api/notes/note_abc123/user-notes', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({ userNotes: updatedNotesWithFile })
});

// Complete example: Mixed content types in user notes
const mixedUserNotes = [
  {
    timestamp: 60.0,
    content: "Introduction to cell biology",
    contentType: "text"
  },
  {
    timestamp: 120.5,
    content: "https://example.com/textbook-chapter-3.pdf",
    contentType: "url"
  },
  {
    timestamp: 180.5,
    content: uploadResult.data.fileUrl, // File attachment
    contentType: "file"
  },
  {
    timestamp: 240.0,
    content: "Key exam topic - memorize this!",
    contentType: "text"
  }
];

await fetch('/api/notes/note_abc123/user-notes', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({ userNotes: mixedUserNotes })
});

Transcription Processing

AI-Powered Transcription

  • Speech Recognition: Advanced AI models for accurate audio-to-text conversion
  • Speed Optimization: Choose between 1x (standard) or 2x speed processing
    • 2x Speed: Cost-optimized transcription (saves ~50% on costs, default)
    • 1x Speed: Standard processing for maximum accuracy
  • Speaker Detection: Identifies different speakers in multi-person recordings
  • Punctuation and Formatting: Automatically adds proper punctuation and paragraph breaks
  • Language Support: Supports multiple languages with automatic detection

Processing Pipeline

  1. Audio Download/Upload: Secure storage of audio files
  2. Format Conversion: Standardization to optimal format for processing
  3. Transcription: AI-powered speech-to-text conversion
  4. Post-Processing: Text cleaning, formatting, and segmentation
  5. Content Analysis: Keyword extraction and topic identification

Quality and Accuracy

  • Confidence Scoring: Each transcription includes accuracy confidence metrics
  • Error Correction: AI-powered grammar and context correction
  • Segment Timing: Precise timestamp alignment for audio synchronization
  • Content Validation: Checks for incomplete or corrupted transcriptions

Processing Status

  • PENDING: Queued for processing
  • PROCESSING: Currently being transcribed
  • COMPLETED: Transcription finished successfully
  • FAILED: Processing encountered an error

Get Study Assets for Note

Retrieve all study assets (quizzes, flashcards, study guides) associated with a specific note.

GET /api/notes/{noteId}/study-assets

Path Parameters

  • noteId: ID of the note to get study assets for (required, string)

Response (200)

{
  "success": true,
  "data": {
    "quizzes": {
      "hasAny": true,
      "count": 1,
      "latest": {
        "id": "quiz_abc123",
        "title": "Biology Chapter 1 Quiz",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "questions": [
          {
            "id": "question_abc123"
          }
        ]
      }
    },
    "flashcards": {
      "hasAny": true,
      "count": 1,
      "latest": {
        "id": "flashcard_set_abc123",
        "title": "Cell Structure Flashcards",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "flashcards": [
          {
            "id": "flashcard_abc123"
          }
        ]
      }
    },
    "studyGuides": {
      "hasAny": false,
      "count": 0,
      "latest": null
    }
  },
  "message": "Study assets retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Note not found or access denied

Get Quizzes for Note

Retrieve all quizzes associated with a specific note.

GET /api/notes/{noteId}/quizzes

Path Parameters

  • noteId: ID of the note to get quizzes for (required, string)

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "quiz_abc123",
      "title": "Biology Chapter 1 Quiz",
      "description": "Assessment on cell structure and function",
      "difficulty": "MEDIUM",
      "courseId": "course_abc123",
      "noteId": "note_abc123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123",
      "course": {
        "id": "course_abc123",
        "name": "Biology 101"
      },
      "note": {
        "id": "note_abc123",
        "title": "Biology Lecture: Cell Structure"
      },
      "questions": [
        {
          "id": "question_abc123",
          "question": "What is the basic unit of life?",
          "type": "multiple_choice",
          "options": ["Cell", "Tissue", "Organ", "Organism"],
          "correctAnswer": "Cell",
          "explanation": "The cell is the basic structural and functional unit of all living organisms.",
          "order": 1,
          "quizId": "quiz_abc123"
        }
      ]
    }
  ],
  "message": "Note quizzes retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Note not found or access denied

Get Flashcards for Note

Retrieve all flashcard sets associated with a specific note.

GET /api/notes/{noteId}/flashcards

Path Parameters

  • noteId: ID of the note to get flashcards for (required, string)

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "flashcard_set_abc123",
      "title": "Cell Structure Flashcards",
      "description": "Key terms and concepts from cell biology lecture",
      "difficulty": "MEDIUM",
      "courseId": "course_abc123",
      "noteId": "note_abc123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123",
      "course": {
        "id": "course_abc123",
        "name": "Biology 101"
      },
      "note": {
        "id": "note_abc123",
        "title": "Biology Lecture: Cell Structure"
      },
      "flashcards": [
        {
          "id": "flashcard_abc123",
          "front": "What is the powerhouse of the cell?",
          "back": "Mitochondria",
          "order": 1,
          "flashcardSetId": "flashcard_set_abc123"
        }
      ]
    }
  ],
  "message": "Note flashcards retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Note not found or access denied

Get Study Guides for Note

Retrieve all study guides associated with a specific note.

GET /api/notes/{noteId}/study-guides

Path Parameters

  • noteId: ID of the note to get study guides for (required, string)

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "study_guide_abc123",
      "title": "Cell Biology Study Guide",
      "content": "# Cell Biology Study Guide\n\n## Key Concepts\n\n### Cell Structure\n- **Nucleus**: Controls cell activities\n- **Mitochondria**: Powerhouse of the cell\n- **Ribosomes**: Protein synthesis\n\n## Important Terms\n- **Cytoplasm**: Gel-like substance inside cell\n- **Organelles**: Specialized structures within cells\n\n## Study Tips\n1. Focus on organelle functions\n2. Understand cell membrane structure\n3. Practice with diagrams",
      "courseId": "course_abc123",
      "noteId": "note_abc123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123",
      "course": {
        "id": "course_abc123",
        "name": "Biology 101"
      },
      "note": {
        "id": "note_abc123",
        "title": "Biology Lecture: Cell Structure"
      }
    }
  ],
  "message": "Note study guides retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Note not found or access denied

Study Asset Generation

Generate Study Assets from Note

Study assets can be generated from notes using the dedicated generation endpoints:

  • Quizzes: POST /api/quizzes/generate with noteIds: [noteId]
  • Flashcards: POST /api/flashcards/generate with noteIds: [noteId]
  • Study Guides: POST /api/study-guides/generate with noteIds: [noteId]

All generation endpoints include deduplication logic - if a study asset already exists for the note, the existing asset is returned instead of creating a duplicate.

Usage Example: Check and Generate Study Assets

// Check existing study assets for a note
const studyAssetsResponse = await fetch('/api/notes/note_abc123/study-assets', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const studyAssets = await studyAssetsResponse.json();

// If no quiz exists, generate one
if (!studyAssets.data.quizzes.hasAny) {
  const generateQuizResponse = await fetch('/api/quizzes/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-token'
    },
    body: JSON.stringify({
      courseId: 'course_abc123',
      noteIds: ['note_abc123'],
      questionCount: 10
    })
  });
  
  const newQuiz = await generateQuizResponse.json();
  console.log('Generated quiz:', newQuiz.data.id);
} else {
  console.log('Quiz already exists:', studyAssets.data.quizzes.latest.id);
}

// Get all flashcards for the note
const flashcardsResponse = await fetch('/api/notes/note_abc123/flashcards', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const flashcards = await flashcardsResponse.json();
console.log('Flashcard sets:', flashcards.data.length);

Integration Notes

  • Notes are automatically organized by course
  • Transcribed content is searchable via universal search
  • Audio files are securely stored with CDN delivery
  • Transcript segments enable precise audio navigation
  • All note operations are scoped to the authenticated user
  • Generated transcripts can be used for study material creation
  • Processing jobs run asynchronously with status tracking
  • Large files are processed in chunks for reliability
  • Study assets are linked to specific notes for targeted learning
  • Deduplication prevents multiple study assets for the same note content
  • Note-specific endpoints provide efficient access to related study materials

Courses API

Course management and organization endpoints

Documents API

Document upload, management, and processing endpoints