TellaAI
API Reference/Core Content

Documents API

Document upload, management, and processing endpoints

Documents API

The Documents API allows users to upload, process, and manage academic documents. Supports various file formats including PDF, DOCX, PPTX, images, and more. Documents are automatically processed for content extraction and can be used to generate study materials.

Document Model

  • id: Unique document identifier (string)
  • title: Document title (string, 1-255 characters)
  • fileName: Original file name (string)
  • fileSize: File size in bytes (number)
  • mimeType: File MIME type (string)
  • filePath: Storage path (string)
  • description: Document description (string, optional)
  • courseId: Associated course ID (string, required)
  • documentType: Document type enum (string)
  • tags: Document tags (array of strings, optional)
  • processed: Processing status (boolean)
  • extractedText: Extracted text content (string, optional)
  • createdAt: ISO datetime when created (string)
  • updatedAt: ISO datetime when last updated (string)
  • userId: Owner user ID (string)

Endpoints

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

Upload Document

Upload a new document file with optional metadata.

POST /api/documents/upload
Content-Type: multipart/form-data

# Form data:
file: [binary file data]
title: "Course Syllabus"
description: "Fall 2024 syllabus for Mathematics 101"
courseId: "course_abc123"
documentType: "SYLLABUS"
tags: ["syllabus", "fall2024"]

Request Body (Multipart Form Data)

  • file: File to upload (required, max 150MB)
  • title: Document title (optional, defaults to filename, 1-255 characters)
  • description: Document description (optional)
  • courseId: Course to associate with (required)
  • documentType: Document type (optional, enum: PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, TXT, SYLLABUS, TEXTBOOK, HANDOUT, ASSIGNMENT, OTHER)
  • tags: Array of tags (optional)

Supported File Types

  • Documents: PDF, DOC, DOCX, TXT, RTF
  • Presentations: PPT, PPTX
  • Images: JPG, JPEG, PNG, GIF, WEBP
  • Spreadsheets: XLS, XLSX, CSV
  • Text: TXT, MD, RTF

Response (200)

{
  "success": true,
  "document": {
    "id": "doc_abc123",
    "title": "Course Syllabus",
    "fileName": "syllabus.pdf",
    "fileSize": 1048576,
    "mimeType": "application/pdf",
    "filePath": "documents/user_123/doc_abc123.pdf",
    "description": "Fall 2024 syllabus for Mathematics 101",
    "courseId": "course_abc123",
    "documentType": "SYLLABUS",
    "tags": ["syllabus", "fall2024"],
    "processed": false,
    "extractedText": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "userId": "user_123"
  }
}

Errors:

  • 400: Invalid file type, file too large, or validation errors
  • 401: Authentication required

Upload Syllabus with Calendar Integration

Upload a syllabus document with automatic calendar event extraction and integration.

POST /api/documents/upload-syllabus
Content-Type: multipart/form-data

# Form data:
file: [binary syllabus file]
courseId: "course_abc123"
title: "Course Syllabus Fall 2024"

Request Body (Multipart Form Data)

  • file: Syllabus file to upload (required)
  • courseId: Course to associate with (required)
  • title: Document title (optional, defaults to filename)
  • description: Document description (optional)

Response (200)

{
  "success": true,
  "document": {
    "id": "doc_abc123",
    "title": "Course Syllabus Fall 2024",
    "fileName": "syllabus.pdf",
    "fileSize": 1048576,
    "mimeType": "application/pdf",
    "documentType": "SYLLABUS",
    "courseId": "course_abc123",
    "processed": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "userId": "user_123"
  },
  "message": "Syllabus uploaded and calendar events extracted successfully"
}

Errors:

  • 400: Invalid file or missing course ID
  • 401: Authentication required
  • 404: Course not found

Search Documents

Search documents with AI-powered semantic and keyword search.

GET /api/documents/search?query=cellular biology

# Advanced search with filters
GET /api/documents/search?query=mitosis&courseId=course_abc123&documentTypes=PDF,DOCX&limit=10

Query Parameters

  • query: Search query (required, 1+ characters)
  • courseId: Filter by course ID (required)
  • documentTypes: Comma-separated document types to filter by (optional)
  • tags: Comma-separated tags to filter by (optional)
  • limit: Maximum number of results (optional, 1-100, default varies)
  • offset: Number of results to skip (optional, default 0)
  • searchType: Type of search (optional, enum: semantic, keyword, hybrid)

Response (200)

{
  "success": true,
  "results": [
    {
      "documentId": "doc_abc123",
      "title": "Biology Chapter 1",
      "documentType": "PDF",
      "relevanceScore": 0.95,
      "snippet": "Cellular biology focuses on the study of cells...",
      "highlights": ["cellular biology", "mitosis", "cell division"],
      "metadata": {
        "author": "Dr. Smith",
        "pageCount": 25,
        "wordCount": 5000,
        "tags": ["biology", "cells"],
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    }
  ],
  "totalCount": 15,
  "suggestions": ["cell biology", "molecular biology", "genetics"]
}

Errors:

  • 400: Invalid search parameters
  • 401: Authentication required

Get All Documents

Retrieve all documents for the authenticated user with optional filtering.

GET /api/documents

# With course filter
GET /api/documents?courseId=course_abc123

# With document type filter
GET /api/documents?documentType=SYLLABUS

# With pagination
GET /api/documents?limit=20&offset=40

Query Parameters

  • courseId: Filter by course ID (required)
  • documentType: Filter by document type (optional)
  • limit: Maximum number of results (optional)
  • offset: Number of results to skip (optional)

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "doc_abc123",
      "title": "Course Syllabus",
      "fileName": "syllabus.pdf",
      "fileSize": 1048576,
      "mimeType": "application/pdf",
      "filePath": "documents/user_123/doc_abc123.pdf",
      "description": "Fall 2024 syllabus for Mathematics 101",
      "courseId": "course_abc123",
      "documentType": "SYLLABUS",
      "tags": ["syllabus", "fall2024"],
      "processed": true,
      "extractedText": "Course: Mathematics 101...",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T12:00:00.000Z",
      "userId": "user_123"
    }
  ],
  "message": "Documents retrieved successfully"
}

Errors:

  • 401: Authentication required

Get Document by ID

Retrieve a specific document by its ID.

GET /api/documents/{id}?courseId=course_abc123

Path Parameters

  • id: Document ID (required)

Query Parameters

  • courseId: Course ID (required)

Response (200)

{
  "success": true,
  "data": {
    "id": "doc_abc123",
    "title": "Course Syllabus",
    "fileName": "syllabus.pdf",
    "fileSize": 1048576,
    "mimeType": "application/pdf",
    "filePath": "documents/user_123/doc_abc123.pdf",
    "description": "Fall 2024 syllabus for Mathematics 101",
    "courseId": "course_abc123",
    "documentType": "SYLLABUS",
    "tags": ["syllabus", "fall2024"],
    "processed": true,
    "extractedText": "Course: Mathematics 101...",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z",
    "userId": "user_123"
  },
  "message": "Document retrieved successfully"
}

Errors:

  • 401: Authentication required
  • 404: Document not found

Update Document (Not Allowed)

Document metadata and content cannot be updated after upload. If you need to make changes, please delete and re-upload the document with the correct information.

Note: All document fields are immutable after creation for data integrity and auditability.

Delete Document

Delete a document and its associated file from storage.

DELETE /api/documents/{id}

Path Parameters

  • id: Document ID (required)

Query Parameters

  • courseId: Course ID (required)

Response (200)

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

Errors:

  • 401: Authentication required
  • 404: Document not found

Generate Study Materials

Generate study materials (flashcards, quizzes, study guides) from a document using AI.

POST /api/documents/{id}/generate
Content-Type: application/json

{
  "types": ["flashcards", "quiz", "study-guide"],
  "options": {
    "difficulty": "MEDIUM",
    "questionCount": 20,
    "focusAreas": ["cellular biology", "mitosis"]
  }
}

Path Parameters

  • id: Document ID (required)

Request Body Parameters

  • types: Array of study material types to generate (required, items: "flashcards", "quiz", "study-guide")
  • options: Generation options (optional)
    • difficulty: Difficulty level (optional, enum: EASY, MEDIUM, HARD)
    • questionCount: Number of questions for quiz (optional, 1-50)
    • focusAreas: Specific topics to focus on (optional, array of strings)

Response (200)

{
  "success": true,
  "results": {
    "flashcards": {
      "id": "flashcard_set_abc123",
      "cardCount": 15
    },
    "quiz": {
      "id": "quiz_def456",
      "questionCount": 20
    },
    "study-guide": {
      "id": "guide_ghi789",
      "sectionCount": 8
    }
  },
  "message": "Study materials generated successfully"
}

Errors:

  • 400: Invalid generation types or options
  • 401: Authentication required
  • 404: Document not found

Document Processing

Automatic Text Extraction

All uploaded documents undergo automatic text extraction:

  • PDF files: OCR and text layer extraction
  • Office documents: Native content extraction
  • Images: OCR text recognition
  • Presentations: Slide text and notes extraction

Processing Status

  • processed: false: Document is being processed or failed
  • processed: true: Text extraction completed successfully
  • extractedText: Contains the extracted content for search and AI operations

File Size Limits

  • Maximum file size: 150MB per document
  • Recommended size: Under 50MB for optimal processing speed
  • Batch uploads: Multiple files can be uploaded sequentially

Usage Examples

Upload and Process Document

// Upload a course document
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('title', 'Course Textbook Chapter 1');
formData.append('courseId', 'course_abc123');
formData.append('documentType', 'TEXTBOOK');
formData.append('tags', JSON.stringify(['textbook', 'chapter1', 'biology']));

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

const result = await response.json();
console.log('Document uploaded:', result.document.id);

Search Documents

// Search for documents related to cellular biology
const response = await fetch('/api/documents/search?query=cellular biology&courseId=course_abc123', {
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

const searchResults = await response.json();
console.log('Found documents:', searchResults.results.length);

Generate Study Materials

// Generate comprehensive study materials from a document
const response = await fetch('/api/documents/doc_abc123/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    types: ['flashcards', 'quiz', 'study-guide'],
    options: {
      difficulty: 'MEDIUM',
      questionCount: 25,
      focusAreas: ['cellular structure', 'organelles', 'cell division']
    }
  })
});

const materials = await response.json();
console.log('Generated:', Object.keys(materials.results));

Integration Notes

  • Documents integrate with all study material generation systems
  • Search functionality includes semantic understanding of document content
  • Syllabus uploads automatically create calendar events
  • All file operations are secured and scoped to the authenticated user
  • Document metadata and file content are immutable after upload.

Notes API

Note creation, import, and audio transcription endpoints

Flashcards API

Flashcard generation and retrieval endpoints