TellaAI
API Reference/Features

Search API

Universal search across academic content with intelligent filtering and suggestions

Search API

The Search API provides comprehensive search functionality across all academic content including courses, notes, documents, flashcards, quizzes, study guides, and calendar events. Features intelligent filtering, suggestions, and relevance-based ranking.

Search Result Model

  • id: Content identifier (string)
  • title: Content title (string)
  • type: Content type (string: "note" | "flashcard_set" | "study_guide" | "quiz" | "course" | "document" | "calendar_event")
  • content: Matched content excerpt (string)
  • description: Content description (string)
  • relevanceScore: Relevance score (number, 0-1)
  • snippet: Contextual snippet with search terms (string)
  • highlights: Array of highlighted text snippets (array)
  • courseId: Associated course ID if applicable (string, optional)
  • courseName: Associated course name if applicable (string, optional)
  • metadata: Additional content metadata (object)
  • createdAt: Content creation date (string, ISO datetime)
  • updatedAt: Content last update date (string, ISO datetime)

Endpoints

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

Search across all content types with a single query and advanced filtering options.

GET /api/search?query=photosynthesis

# With content type filters
GET /api/search?query=photosynthesis&types=document,note

# With course filter
GET /api/search?query=photosynthesis&courseId=course_abc123

# With pagination
GET /api/search?query=photosynthesis&limit=25&offset=50

# With multiple filters
GET /api/search?query=biology&types=note,document&difficulty=MEDIUM&startDate=2024-01-01&endDate=2024-01-31&minRelevance=0.5

Query Parameters

  • query: Search query (required, 1-500 characters)
  • types: Comma-separated content types to search (optional: "note,flashcard_set,study_guide,quiz,course,document,calendar_event")
  • courseId: Filter by specific course ID (optional)
  • limit: Maximum number of results (optional, 1-100, default: 50)
  • offset: Number of results to skip for pagination (optional, default: 0)
  • minRelevance: Minimum relevance score (optional, 0.0-1.0, default: 0.1)
  • startDate: Filter by creation date start (optional, YYYY-MM-DD format)
  • endDate: Filter by creation date end (optional, YYYY-MM-DD format)
  • difficulty: Comma-separated difficulty levels (optional: "EASY,MEDIUM,HARD")
  • status: Comma-separated status values (optional: "COMPLETED,PROCESSING,FAILED")

Response (200)

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "document_abc123",
        "title": "Photosynthesis in Plant Cells",
        "type": "document",
        "content": "Photosynthesis is the process by which plants convert light energy into chemical energy...",
        "description": "Comprehensive guide to photosynthesis processes",
        "relevanceScore": 0.95,
        "snippet": "Photosynthesis is the process by which plants convert light energy into chemical energy",
        "highlights": [
          "Photosynthesis is the process by which plants convert light energy into chemical energy"
        ],
        "courseId": "course_abc123",
        "courseName": "Biology 101",
        "metadata": {
          "fileName": "biology_chapter_6.pdf",
          "fileSize": 1048576,
          "pages": 25
        },
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T12:00:00.000Z"
      },
      {
        "id": "note_def456",
        "title": "Lecture Notes: Plant Biology",
        "type": "note",
        "content": "Today we discussed photosynthesis and cellular respiration...",
        "description": "Notes from Biology lecture covering photosynthesis",
        "relevanceScore": 0.87,
        "snippet": "photosynthesis and cellular respiration mechanisms",
        "highlights": [
          "photosynthesis and cellular respiration"
        ],
        "courseId": "course_abc123",
        "courseName": "Biology 101",
        "metadata": {
          "transcript": true,
          "duration": 3600,
          "status": "COMPLETED"
        },
        "createdAt": "2024-01-02T00:00:00.000Z",
        "updatedAt": "2024-01-02T10:00:00.000Z"
      }
    ],
    "totalCount": 25,
    "suggestions": [
      "photosynthesis process",
      "photosynthesis equation",
      "chloroplast function"
    ],
    "searchTime": 45,
    "resultsByType": {
      "document": 12,
      "note": 8,
      "flashcard_set": 3,
      "quiz": 2
    },
    "query": "photosynthesis",
    "filters": {
      "types": ["document", "note"],
      "courseId": "course_abc123"
    },
    "pagination": {
      "limit": 50,
      "offset": 0,
      "hasMore": false
    }
  },
  "message": "Found 25 results in 45ms"
}

Errors:

  • 400: Invalid search query or parameters
  • 401: Authentication required
  • 500: Internal search error

Get Search Filters

Retrieve available filter options for search refinement.

GET /api/search/filters

Response (200)

{
  "success": true,
  "data": {
    "types": [
      {
        "value": "note",
        "label": "Notes",
        "icon": "📝"
      },
      {
        "value": "flashcard_set",
        "label": "Flashcard Sets",
        "icon": "🧠"
      },
      {
        "value": "study_guide",
        "label": "Study Guides",
        "icon": "📚"
      },
      {
        "value": "quiz",
        "label": "Quizzes",
        "icon": "❓"
      },
      {
        "value": "course",
        "label": "Courses",
        "icon": "🎓"
      },
      {
        "value": "document",
        "label": "Documents",
        "icon": "📄"
      },
      {
        "value": "calendar_event",
        "label": "Calendar Events",
        "icon": "📅"
      }
    ],
    "courses": [
      {
        "value": "course_abc123",
        "label": "Biology 101 (Dr. Smith)",
        "semester": "Fall 2024"
      },
      {
        "value": "course_def456",
        "label": "Chemistry 101 (Dr. Johnson)",
        "semester": "Fall 2024"
      }
    ],
    "difficulty": [
      {
        "value": "EASY",
        "label": "Easy",
        "color": "green"
      },
      {
        "value": "MEDIUM",
        "label": "Medium",
        "color": "yellow"
      },
      {
        "value": "HARD",
        "label": "Hard",
        "color": "red"
      }
    ],
    "status": [
      {
        "value": "COMPLETED",
        "label": "Completed",
        "color": "green"
      },
      {
        "value": "PROCESSING",
        "label": "Processing",
        "color": "blue"
      },
      {
        "value": "FAILED",
        "label": "Failed",
        "color": "red"
      }
    ],
    "dateRanges": [
      {
        "value": "today",
        "label": "Today"
      },
      {
        "value": "week",
        "label": "This Week"
      },
      {
        "value": "month",
        "label": "This Month"
      },
      {
        "value": "semester",
        "label": "This Semester"
      },
      {
        "value": "custom",
        "label": "Custom Range"
      }
    ]
  },
  "message": "Search filters retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 500: Failed to get search filters

Get Search Suggestions

Get search query suggestions and autocomplete options based on partial input.

GET /api/search/suggestions?query=photo

Query Parameters

  • query: Partial search query for suggestions (required, 2-100 characters)

Response (200)

{
  "success": true,
  "data": {
    "suggestions": [
      "photosynthesis",
      "photosynthesis process", 
      "photosynthesis equation",
      "Biology 101",
      "photo notes",
      "photo flashcards",
      "photo study guide",
      "photography"
    ]
  },
  "message": "Search suggestions retrieved successfully"
}

Errors:

  • 400: Query too short (must be at least 2 characters)
  • 401: Authentication required
  • 500: Failed to get search suggestions

Search Features

Content Types Searchable

The system searches across all major content types:

  • Notes: Note content, transcriptions, titles
  • Flashcard Sets: Card questions and answers, set titles
  • Study Guides: Guide content, section titles, key terms
  • Quizzes: Question content, quiz titles and descriptions
  • Courses: Course names, descriptions, professor names
  • Documents: File content, titles, descriptions, metadata
  • Calendar Events: Event titles, descriptions, locations

Advanced Filtering

Content Type Filtering

Filter results by specific content types using comma-separated values:

types=note,document,flashcard_set

Course-Based Filtering

Limit search to specific courses:

courseId=course_abc123

Date Range Filtering

Filter content by creation date:

startDate=2024-01-01&endDate=2024-01-31

Difficulty Filtering

Filter by content difficulty level:

difficulty=EASY,MEDIUM

Status Filtering

Filter by processing status:

status=COMPLETED,PROCESSING

Relevance Filtering

Set minimum relevance threshold:

minRelevance=0.5

Search Intelligence

  • Relevance Scoring: Results ranked by relevance to query (0-1 scale)
  • Query Suggestions: Intelligent autocomplete based on content and search history
  • Snippet Extraction: Contextual excerpts showing search term matches
  • Highlight Matching: Matched terms highlighted in results
  • Cross-Content Search: Single query searches all content types simultaneously

Pagination

Results use offset-based pagination:

  • limit: Number of results per page (1-100, default: 50)
  • offset: Number of results to skip
  • hasMore: Boolean indicating if more results are available
  • totalCount: Total number of matching results

Example pagination:

# First page (results 1-50)
GET /api/search?query=biology&limit=50&offset=0

# Second page (results 51-100)  
GET /api/search?query=biology&limit=50&offset=50

Response Performance

  • Search Time: Millisecond timing included in response
  • Result Breakdown: Count of results by content type
  • Smart Caching: Frequently searched terms cached for faster responses
  • Async Processing: Long-running searches handled asynchronously

Error Responses

All endpoints return consistent error responses:

{
  "success": false,
  "error": "Error message description",
  "code": "ERROR_CODE",
  "details": ["Additional validation errors"]
}

Common error codes:

  • UNAUTHORIZED: Authentication required
  • VALIDATION_ERROR: Invalid search parameters
  • QUERY_TOO_SHORT: Search query too short (suggestions)
  • INVALID_LIMIT: Limit out of valid range (1-100)
  • INVALID_OFFSET: Offset must be 0 or greater
  • INVALID_MIN_RELEVANCE: Relevance score out of range (0-1)
  • INVALID_DATE_RANGE: Start date must be before end date
  • SEARCH_FAILED: Internal search error
  • FILTERS_FAILED: Failed to retrieve filters
  • SUGGESTIONS_FAILED: Failed to generate suggestions

Integration Examples

// Simple text search
const response = await fetch('/api/search?query=photosynthesis');
const data = await response.json();
// Search with filters
const params = new URLSearchParams({
  query: 'biology',
  types: 'note,document', 
  courseId: 'course_abc123',
  difficulty: 'MEDIUM',
  limit: '25'
});

const response = await fetch(`/api/search?${params}`);
const data = await response.json();

Search with Pagination

// Paginated results
const response = await fetch('/api/search?query=chemistry&limit=20&offset=40');
const data = await response.json();

console.log(`Showing results ${data.data.pagination.offset + 1}-${data.data.pagination.offset + data.data.results.length} of ${data.data.totalCount}`);

Search Suggestions

// Get autocomplete suggestions
const response = await fetch('/api/search/suggestions?query=bio');
const data = await response.json();
const suggestions = data.data.suggestions;

Calendar API

Academic calendar and event management endpoints with Google Calendar integration

Dashboard API

Dashboard data aggregation and overview endpoint