TellaAI
API Reference/Features

Calendar API

Academic calendar and event management endpoints with Google Calendar integration

Calendar API

The Calendar API allows users to manage their academic calendar, including classes, deadlines, exams, and study sessions. Features local event management with Google Calendar synchronization capabilities.

Calendar Event Model

  • id: Unique event identifier (string)
  • title: Event title (string, required, 1-255 characters)
  • description: Event description (string, optional, max 1000 characters)
  • startDate: Event start date/time (string, required, ISO datetime)
  • endDate: Event end date/time (string, optional, ISO datetime)
  • eventType: Type of event (string: "CLASS" | "DEADLINE" | "EXAM" | "MEETING" | "STUDY_SESSION")
  • location: Event location (string, optional, max 255 characters)
  • priority: Event priority level (string: "LOW" | "MEDIUM" | "HIGH")
  • color: Display color for event (string, required)
  • courseId: Associated course ID (string, optional)
  • googleEventId: Google Calendar event ID (string, auto-generated)
  • googleCalendarId: Google Calendar ID (string, auto-generated)
  • userId: Owner user ID (string)
  • createdAt: ISO datetime when created (string)
  • updatedAt: ISO datetime when last updated (string)

Endpoints

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

Create Event

Create a new calendar event with optional Google Calendar sync.

POST /api/calendar/events
Content-Type: application/json

{
  "title": "Biology Lecture",
  "description": "Cell structure and function",
  "startDate": "2024-01-15T10:00:00.000Z",
  "endDate": "2024-01-15T11:30:00.000Z",
  "eventType": "CLASS",
  "location": "Science Building Room 101",
  "priority": "MEDIUM",
  "color": "blue",
  "courseId": "course_abc123"
}

Request Body Parameters

  • title: Event title (required, 1-255 characters)
  • description: Event description (optional, max 1000 characters)
  • startDate: Start date/time in ISO format (required)
  • endDate: End date/time in ISO format (optional)
  • eventType: Event type (required, "CLASS" | "DEADLINE" | "EXAM" | "MEETING" | "STUDY_SESSION")
  • location: Event location (optional, max 255 characters)
  • priority: Priority level (optional, "LOW" | "MEDIUM" | "HIGH")
  • color: Display color (required, hex code or color name)
  • courseId: Associated course ID (optional)

Response (201)

{
  "success": true,
  "data": {
    "id": "event_abc123",
    "title": "Biology Lecture",
    "description": "Cell structure and function",
    "startDate": "2024-01-15T10:00:00.000Z",
    "endDate": "2024-01-15T11:30:00.000Z",
    "eventType": "CLASS",
    "location": "Science Building Room 101",
    "priority": "MEDIUM",
    "color": "blue",
    "googleEventId": "google_event_xyz789",
    "googleCalendarId": "primary",
    "courseId": "course_abc123",
    "userId": "user_123",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "message": "Calendar event created successfully"
}

Errors:

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

Get Events

Retrieve calendar events with optional filtering and pagination.

GET /api/calendar/events

# Filter by date range
GET /api/calendar/events?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z

# Filter by event type
GET /api/calendar/events?eventType=CLASS

# Filter by course
GET /api/calendar/events?courseId=course_abc123

# Pagination
GET /api/calendar/events?limit=25&offset=0

Query Parameters

  • startDate: Filter events starting from this date (optional, ISO datetime)
  • endDate: Filter events ending before this date (optional, ISO datetime)
  • eventType: Filter by event type (optional, "CLASS" | "DEADLINE" | "EXAM" | "MEETING" | "STUDY_SESSION")
  • courseId: Filter by course ID (optional)
  • limit: Number of events to return (optional, 1-100, default: 50)
  • offset: Number of events to skip (optional, default: 0)

Response (200)

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "event_abc123",
        "title": "Biology Lecture",
        "description": "Cell structure and function",
        "startDate": "2024-01-15T10:00:00.000Z",
        "endDate": "2024-01-15T11:30:00.000Z",
        "eventType": "CLASS",
        "location": "Science Building Room 101",
        "priority": "MEDIUM",
        "color": "blue",
        "googleEventId": "google_event_xyz789",
        "googleCalendarId": "primary",
        "courseId": "course_abc123",
        "userId": "user_123",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "course": {
          "id": "course_abc123",
          "name": "Biology 101",
          "code": "BIO101"
        },
        "user": {
          "id": "user_123",
          "name": "John Doe"
        }
      }
    ],
    "pagination": {
      "total": 100,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  },
  "message": "Calendar events retrieved successfully"
}

Errors:

  • 400: Invalid query parameters
  • 401: Authentication required

Get Event by ID

Retrieve a specific calendar event.

GET /api/calendar/events/{id}

Path Parameters

  • id: Event ID (required)

Response (200)

Returns the same structure as the create event response.

Errors:

  • 400: Invalid event ID
  • 401: Authentication required
  • 404: Event not found

Update Event

Update an existing calendar event with optional Google Calendar sync.

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

{
  "title": "Updated Biology Lecture",
  "location": "Science Building Room 205",
  "priority": "HIGH",
  "startDate": "2024-01-15T10:30:00.000Z"
}

Path Parameters

  • id: Event ID (required)

Request Body

All fields are optional for updates:

  • title: Event title (1-255 characters)
  • description: Event description (max 1000 characters)
  • startDate: Start date/time in ISO format
  • endDate: End date/time in ISO format
  • eventType: Event type ("CLASS" | "DEADLINE" | "EXAM" | "MEETING" | "STUDY_SESSION")
  • location: Event location (max 255 characters)
  • priority: Priority level ("LOW" | "MEDIUM" | "HIGH")
  • color: Display color
  • courseId: Associated course ID (can be null)

Response (200)

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

Errors:

  • 400: Invalid input data or validation errors
  • 401: Authentication required
  • 404: Event not found

Delete Event

Delete a calendar event from local database and optionally from Google Calendar.

DELETE /api/calendar/events/{id}

Path Parameters

  • id: Event ID (required)

Response (200)

{
  "success": true,
  "message": "Calendar event deleted successfully"
}

Errors:

  • 400: Invalid event ID
  • 401: Authentication required
  • 404: Event not found

Google Calendar Integration

Sync from Google Calendar

Import events from Google Calendar to local database.

POST /api/calendar/sync/google

Response (200)

{
  "success": true,
  "data": {
    "imported": 15,
    "updated": 3
  },
  "message": "Sync completed: 15 imported, 3 updated"
}

Errors:

  • 400: Google Calendar not linked to account
  • 401: Authentication required

Google Calendar Features

  • Automatic Sync: Events created locally can be automatically synced to Google Calendar
  • Two-way Sync: Import existing Google Calendar events to local database
  • OAuth Integration: Requires Google OAuth authentication with calendar permissions
  • Conflict Resolution: Updates existing events if they already exist locally

Event Types

The system supports the following event types:

  • CLASS: Regular class sessions, lectures, labs
  • EXAM: Tests, finals, midterms, quizzes
  • DEADLINE: Assignment due dates, project deadlines
  • MEETING: Office hours, group meetings, conferences
  • STUDY_SESSION: Personal study time, group study sessions

Priority Levels

Events can be assigned priority levels for better organization:

  • LOW: Optional events, low-priority tasks
  • MEDIUM: Regular importance events (default)
  • HIGH: Critical events requiring immediate attention

Error Responses

All endpoints return consistent error responses with specific error codes and actionable guidance:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "SPECIFIC_ERROR_CODE",
  "action": "SUGGESTED_ACTION",
  "details": ["Additional validation errors"]
}

Error Categories

Authentication Errors

  • UNAUTHORIZED: Authentication required - user must log in
  • GOOGLE_CALENDAR_AUTH_ERROR: Google Calendar authentication failed
    • Action: RELINK_GOOGLE_ACCOUNT
    • Message: User needs to reconnect their Google account

Validation Errors

  • VALIDATION_ERROR: Invalid input data with detailed validation errors
  • CALENDAR_EVENT_NOT_FOUND: Specified calendar event does not exist

Google Calendar Integration Errors

  • GOOGLE_CALENDAR_NOT_LINKED: Google Calendar not connected to account
    • Action: LINK_GOOGLE_ACCOUNT
    • Message: User needs to connect their Google account to sync calendar events
  • GOOGLE_CALENDAR_PERMISSION_ERROR: Insufficient permissions for Google Calendar
    • Action: CHECK_GOOGLE_PERMISSIONS
    • Message: User needs to verify Google Calendar permissions
  • GOOGLE_CALENDAR_RATE_LIMIT: Google Calendar API rate limit exceeded
    • Action: RETRY_LATER
    • Message: User should wait before trying again
  • GOOGLE_CALENDAR_SYNC_ERROR: Failed to sync with Google Calendar

Operation Errors

  • CALENDAR_EVENT_CREATE_ERROR: Failed to create calendar event
  • CALENDAR_EVENT_UPDATE_ERROR: Failed to update calendar event
  • CALENDAR_EVENT_DELETE_ERROR: Failed to delete calendar event
  • CALENDAR_SERVICE_ERROR: Generic calendar service error

Error Handling Best Practices

  1. Check Error Codes: Always check the code field for specific error handling
  2. Use Action Fields: The action field provides guidance on user actions
  3. Display User-Friendly Messages: Show the error message to users
  4. Handle Google Calendar Errors: Provide buttons to reconnect Google accounts
  5. Implement Retry Logic: For rate limit errors, implement exponential backoff

Example Error Handling

// Frontend error handling example
try {
  const response = await calendarApi.syncFromGoogle();
  if (!response.success) {
    switch (response.code) {
      case 'GOOGLE_CALENDAR_NOT_LINKED':
        showConnectGoogleButton();
        break;
      case 'GOOGLE_CALENDAR_AUTH_ERROR':
        showReconnectGoogleButton();
        break;
      case 'GOOGLE_CALENDAR_RATE_LIMIT':
        showRetryLaterMessage();
        break;
      default:
        showGenericErrorMessage(response.error);
    }
  }
} catch (error) {
  handleNetworkError(error);
}

Common Error Scenarios

Google Calendar Not Linked

When users try to sync without linking their Google account:

{
  "success": false,
  "error": "Google Calendar not linked to this account. Please connect your Google account to sync calendar events.",
  "code": "GOOGLE_CALENDAR_NOT_LINKED",
  "action": "LINK_GOOGLE_ACCOUNT"
}

Rate Limit Exceeded

When Google Calendar API rate limits are hit:

{
  "success": false,
  "error": "Google Calendar rate limit exceeded. Please try again later.",
  "code": "GOOGLE_CALENDAR_RATE_LIMIT",
  "action": "RETRY_LATER"
}

Authentication Expired

When Google Calendar authentication has expired:

{
  "success": false,
  "error": "Google Calendar authentication failed. Please reconnect your Google account.",
  "code": "GOOGLE_CALENDAR_AUTH_ERROR",
  "action": "RELINK_GOOGLE_ACCOUNT"
}

Chat API

AI chat conversation management and streaming endpoints

Search API

Universal search across academic content with intelligent filtering and suggestions