Courses API

The Courses API allows users to manage their academic courses, including creating, updating, retrieving, and deleting course information. Each course acts as a container for notes, study materials, and related academic content.

Quick Start Workflow

Create a Course

Start by creating a new course to organize your academic content:

const response = await fetch('/api/courses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Biology 101',
    professor: 'Dr. Sarah Wilson',
    semester: 'Spring 2024',
    color: 'green',
    emoji: '🧬'
  })
});

Add Course Materials

Upload documents and notes to your course (see Documents API and Notes API):

// Upload course materials
await fetch('/api/documents/upload', {
  method: 'POST',
  body: formData // with courseId included
});

Generate Study Materials

Create flashcards, quizzes, and study guides from your course content:

// Generate flashcards from course documents
await fetch('/api/flashcards/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sourceType: 'document',
    sourceId: 'document_id',
    difficulty: 'MEDIUM'
  })
});

Organize and Study

Use your course as a central hub to access all related materials and track your academic progress.

Course Model

Prop	Type	Default
`id?`	`string`	-
`name?`	`string`	-
`professor?`	`string`	-
`semester?`	`string`	-
`location?`	`string \| undefined`	-
`description?`	`string \| undefined`	-
`color?`	`string`	-
`emoji?`	`string`	-
`createdAt?`	`string`	-
`updatedAt?`	`string`	-
`userId?`	`string`	-

Endpoints

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

Create Course

Create a new course for the authenticated user.

POST /api/courses
Content-Type: application/json

{
  "name": "Mathematics 101",
  "professor": "Dr. Jane Smith",
  "semester": "Fall 2024",
  "location": "Room 205A",
  "description": "Introduction to calculus and mathematical analysis",
  "color": "blue",
  "emoji": "📐"
}

Request Body

Prop	Type	Default
`name?`	`string`	`Required, 1-255 characters`
`professor?`	`string`	`Required, 1-255 characters`
`semester?`	`string`	`Required, 1-50 characters`
`color?`	`string`	`Required, 1-50 characters`
`emoji?`	`string`	`Required, 1-10 characters`
`location?`	`string \| undefined`	`Optional, max 255 characters`
`description?`	`string \| undefined`	`Optional, max 1000 characters`

Response (201)

Prop	Type	Default
`success?`	`boolean`	`true`
`data?`	`Course`	-
`message?`	`string`	-

{
  "success": true,
  "data": {
    "id": "course_abc123",
    "name": "Mathematics 101",
    "professor": "Dr. Jane Smith",
    "semester": "Fall 2024",
    "location": "Room 205A",
    "description": "Introduction to calculus and mathematical analysis",
    "color": "blue",
    "emoji": "📐",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "userId": "user_123"
  },
  "message": "Course created successfully"
}

Errors:

400: Invalid input data or validation errors
401: Authentication required

Get All Courses

Retrieve all courses for the authenticated user with optional search.

GET /api/courses

# With search
GET /api/courses?search=mathematics

Query Parameters

Prop	Type	Default
`search?`	`string \| undefined`	`Optional, max 255 characters`

Response (200)

Prop	Type	Default
`success?`	`boolean`	`true`
`data?`	`Course[]`	-
`message?`	`string`	-

{
  "success": true,
  "data": [
    {
      "id": "course_abc123",
      "name": "Mathematics 101",
      "professor": "Dr. Jane Smith",
      "semester": "Fall 2024",
      "location": "Room 205A",
      "description": "Introduction to calculus and mathematical analysis",
      "color": "blue",
      "emoji": "📐",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "userId": "user_123"
    }
  ],
  "message": "Courses retrieved successfully"
}

Errors:

401: Authentication required

Get Course by ID

Retrieve a specific course by its ID.

GET /api/courses/{id}

Path Parameters

Prop	Type	Default
`id?`	`string`	`Required`

Response (200)

Returns the same structure as the create course response.

Errors:

401: Authentication required
404: Course not found

Update Course

Update an existing course. Only provided fields will be updated.

PATCH /api/courses/{id}
Content-Type: application/json

{
  "name": "Advanced Mathematics 101",
  "description": "Updated course description",
  "location": "Room 305B"
}

Path Parameters

Prop	Type	Default
`id?`	`string`	`Required`

Request Body

All fields are optional for updates:

Prop	Type	Default
`name?`	`string \| undefined`	`1-255 characters`
`professor?`	`string \| undefined`	`1-255 characters`
`semester?`	`string \| undefined`	`1-50 characters`
`location?`	`string \| undefined`	`Max 255 characters`
`description?`	`string \| undefined`	`Max 1000 characters`
`color?`	`string \| undefined`	`1-50 characters`
`emoji?`	`string \| undefined`	`1-10 characters`

Response (200)

Returns the updated course object with the same structure as create course.

Errors:

401: Authentication required
404: Course not found

Delete Course

Delete a course and all associated content (notes, flashcards, quizzes, etc.).

DELETE /api/courses/{id}

Path Parameters

Prop	Type	Default
`id?`	`string`	`Required`

Response (200)

Prop	Type	Default
`success?`	`boolean`	`true`
`message?`	`string`	-

{
  "success": true,
  "message": "Course deleted successfully"
}

Errors:

401: Authentication required
404: Course not found

Authentication

All endpoints require session-based authentication. Users must be authenticated through the /api/auth/signin endpoint first.

Validation Rules

Course Name

Required field
1-255 characters
Cannot be empty or just whitespace

Professor

Required field
1-255 characters
Cannot be empty or just whitespace

Semester

Required field
1-50 characters
Common formats: "Fall 2024", "Spring 2025", "Summer 2024"

Color

Required field
1-50 characters
Common values: "blue", "green", "red", "purple", "orange"

Emoji

Required field
1-10 characters
Should be a valid emoji character

Location (Optional)

Maximum 255 characters
Common formats: "Room 205A", "Online", "Lab Building"

Description (Optional)

Maximum 1000 characters
Can include course overview, prerequisites, etc.

Courses serve as containers for:

Notes: Lecture notes, transcriptions, and documents
Flashcard Sets: Study flashcards organized by course
Quizzes: Assessment materials
Study Guides: Generated study materials
Calendar Events: Course-related events and deadlines
Documents: Course materials and uploads

Usage Examples

Create a Basic Course

const response = await fetch('/api/courses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Biology 101',
    professor: 'Dr. Sarah Wilson',
    semester: 'Spring 2024',
    color: 'green',
    emoji: '🧬'
  })
});

Search for Courses

const response = await fetch('/api/courses?search=math');
const data = await response.json();
console.log(data.data); // Array of matching courses

Update Course Information

const response = await fetch('/api/courses/course_abc123', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    location: 'Online',
    description: 'Course moved to online format'
  })
});

Courses API

On this page