NeuroForge API Reference

Base URL: http://localhost:8000

Interactive docs: http://localhost:8000/docs (Swagger UI)

Health & Status
Subject Management
Document Management
Source Attribution (Citations)
Quiz Generation
Flashcard Generation
Revision Notes
Solution Generation
Chat Tutor
Additional Info
Mind Map
Spaced Repetition

Health & Status

GET /

Welcome message and API info.

Response:

{
  "message": "Welcome to NeuroForge API",
  "version": "0.1.0",
  "docs": "/docs"
}

GET /health

System health check.

Response:

{
  "status": "healthy",
  "message": "All components operational",
  "components": {
    "llm_client": true,
    "vector_store": true,
    "knowledge_graph": true,
    "retriever": true
  }
}

GET /stats

Usage statistics.

Response:

{
  "documents_processed": 5,
  "total_chunks": 234,
  "concepts_extracted": 45,
  "quizzes_generated": 12,
  "flashcards_generated": 89
}

Subject Management

Subjects allow you to organize study materials into separate, isolated collections.

POST /subjects

Create a new subject.

Request:

{
  "name": "Physics",
  "description": "Classical mechanics and thermodynamics",
  "color": "#3B82F6",
  "icon": "📐"
}

Field	Type	Required	Description
name	string	Yes	Subject name (must be unique)
description	string	No	Optional description
color	string	No	Hex color code for UI
icon	string	No	Emoji icon for subject

Response:

{
  "id": "subj_abc123",
  "name": "Physics",
  "description": "Classical mechanics and thermodynamics",
  "color": "#3B82F6",
  "icon": "📐",
  "created_at": "2026-08-06T12:00:00Z",
  "is_default": false,
  "is_archived": false
}

GET /subjects

List all subjects.

Query Parameters:

Parameter	Type	Default	Description
include_archived	bool	false	Include archived subjects

Response:

{
  "subjects": [
    {
      "id": "subj_default",
      "name": "General",
      "description": "Default subject for all materials",
      "color": "#6B7280",
      "icon": "📚",
      "is_default": true,
      "is_archived": false,
      "document_count": 5,
      "flashcard_count": 89,
      "last_activity": "2026-08-06T14:30:00Z"
    },
    {
      "id": "subj_abc123",
      "name": "Physics",
      "description": "Classical mechanics and thermodynamics",
      "color": "#3B82F6",
      "icon": "📐",
      "is_default": false,
      "is_archived": false,
      "document_count": 3,
      "flashcard_count": 45,
      "last_activity": "2026-08-05T10:15:00Z"
    }
  ]
}

GET /subjects/{subject_id}

Get full subject details with statistics.

Response:

{
  "id": "subj_abc123",
  "name": "Physics",
  "description": "Classical mechanics and thermodynamics",
  "color": "#3B82F6",
  "icon": "📐",
  "created_at": "2026-08-01T09:00:00Z",
  "updated_at": "2026-08-06T14:30:00Z",
  "is_default": false,
  "is_archived": false,
  "stats": {
    "document_count": 3,
    "chunk_count": 156,
    "concept_count": 45,
    "flashcard_count": 45,
    "quiz_count": 12,
    "mastery_percent": 72.5
  }
}

PUT /subjects/{subject_id}

Update a subject.

Request:

{
  "name": "Physics 101",
  "description": "Updated description",
  "color": "#8B5CF6"
}

Response: Updated subject object.

DELETE /subjects/{subject_id}

Delete a subject and all its data.

Note: Cannot delete the default "General" subject.

Response:

{
  "message": "Subject deleted successfully",
  "subject_id": "subj_abc123"
}

POST /subjects/{subject_id}/archive

Archive a subject (hide from main list but preserve data).

Response:

{
  "message": "Subject archived",
  "subject_id": "subj_abc123"
}

POST /subjects/{subject_id}/restore

Restore an archived subject.

Response:

{
  "message": "Subject restored",
  "subject_id": "subj_abc123"
}

GET /subjects/{subject_id}/documents

List all documents in a subject.

Response:

{
  "documents": [
    {
      "id": "doc_abc123",
      "filename": "classical-mechanics.pdf",
      "status": "completed",
      "chunks": 78,
      "uploaded_at": "2026-08-01T12:00:00Z"
    }
  ]
}

DELETE /subjects/{subject_id}/documents/{doc_id}

Remove a document from a subject.

Response:

{
  "message": "Document removed from subject",
  "document_id": "doc_abc123"
}

Document Management

POST /upload

Upload a document for processing.

Request:

Content-Type: multipart/form-data
Body: file (PDF, DOCX, or TXT)

Response:

{
  "document_id": "doc_abc123",
  "filename": "engineering-materials.pdf",
  "status": "processing",
  "message": "Document uploaded successfully. Processing started."
}

GET /documents

List all uploaded documents.

Response:

{
  "documents": [
    {
      "id": "doc_abc123",
      "filename": "engineering-materials.pdf",
      "status": "completed",
      "chunks": 156,
      "uploaded_at": "2026-08-06T12:00:00Z"
    }
  ]
}

GET /progress/{document_id}

Get processing progress for a document.

Response:

{
  "document_id": "doc_abc123",
  "status": "processing",
  "progress": 65,
  "stage": "extracting_concepts",
  "message": "Extracting knowledge concepts..."
}

Status values: pending, processing, completed, failed

Source Attribution (Citations)

Source attribution allows users to trace generated content (quizzes, flashcards, notes) back to their original source documents. Citations are automatically included in generation responses and can be used to open an inline document viewer.

Citation Object

All citation objects have this structure:

{
  "id": "cit_abc123",
  "chunk_id": "e2dc90d3_0047",
  "document_id": "doc_xyz789",
  "document_name": "engineering-materials.pdf",
  "document_format": "pdf",
  "page_number": 12,
  "paragraph_number": 3,
  "excerpt": "Martensite forms through a shear transformation when steel is rapidly cooled...",
  "full_text": "Martensite forms through a shear transformation when steel is rapidly cooled from above the critical temperature. This diffusionless transformation...",
  "relevance_score": 0.92,
  "bounding_boxes": [
    {"x0": 10.5, "y0": 45.2, "x1": 85.3, "y1": 52.8, "page_width": 100, "page_height": 100}
  ],
  "start_char": 1234,
  "end_char": 1567,
  "line_start": 45,
  "line_end": 52,
  "section_heading": "Heat Treatment Processes"
}

Field	Type	Description
id	string	Unique citation ID
chunk_id	string	Original chunk ID from vector store
document_id	string	Source document ID
document_name	string	Original filename
document_format	string	File format (pdf, docx, txt)
page_number	int	Page number (1-indexed, PDF only)
paragraph_number	int	Paragraph number within page
excerpt	string	Truncated text (~200 chars)
full_text	string	Complete chunk text
relevance_score	float	Similarity score (0-1)
bounding_boxes	array	Highlight coordinates (PDF)
start_char	int	Character offset in document
end_char	int	Character end offset
line_start	int	Starting line (text files)
line_end	int	Ending line (text files)
section_heading	string	Section/heading context

GET /chunks/{chunk_id}/citation

Get full citation for a single chunk.

Response:

{
  "status": "success",
  "citation": {
    "id": "cit_abc123",
    "chunk_id": "e2dc90d3_0047",
    "document_name": "engineering-materials.pdf",
    ...
  }
}

POST /citations/batch

Get citations for multiple chunks efficiently.

Request:

{
  "chunk_ids": ["e2dc90d3_0047", "e2dc90d3_0048", "e2dc90d3_0049"],
  "subject_id": "subj_abc123"
}

Response:

{
  "status": "success",
  "citations": [
    {"id": "cit_001", "chunk_id": "e2dc90d3_0047", ...},
    {"id": "cit_002", "chunk_id": "e2dc90d3_0048", ...},
    {"id": "cit_003", "chunk_id": "e2dc90d3_0049", ...}
  ],
  "count": 3
}

GET /subjects/{subject_id}/documents/{doc_id}/file

Serve the original document file for viewing.

Headers:

Range (optional): Byte range for streaming (e.g., bytes=0-1023)

Response:

Content-Type: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, or text/plain
Content-Disposition: inline; filename="document.pdf"
Supports partial content (206) for Range requests

GET /subjects/{subject_id}/documents/{doc_id}/chunks

List all chunks from a specific document.

Response:

{
  "status": "success",
  "document_id": "doc_xyz789",
  "document_name": "engineering-materials.pdf",
  "chunks": [
    {
      "id": "e2dc90d3_0001",
      "page_number": 1,
      "content_preview": "Chapter 1: Introduction to Materials..."
    }
  ],
  "total_chunks": 156
}

Citations in Generation Responses

All content generation endpoints (quiz, flashcards, notes, chat) now include citations automatically:

Quiz Response with Citations:

{
  "questions": [
    {
      "id": "q-001",
      "question": "What microstructure forms when steel is rapidly cooled?",
      "correct_answer": "Martensite",
      "explanation": "Rapid cooling prevents diffusion...",
      "source_chunk_ids": ["e2dc90d3_0047", "e2dc90d3_0048"],
      "citations": [
        {
          "id": "cit_001",
          "document_name": "engineering-materials.pdf",
          "page_number": 12,
          "excerpt": "Martensite forms through a shear transformation...",
          "relevance_score": 0.92
        }
      ]
    }
  ]
}

Chat Response with Citations:

{
  "answer": "Martensite forms when steel is rapidly cooled...",
  "sources": ["e2dc90d3_0047", "e2dc90d3_0048"],
  "is_grounded": true,
  "citations": [
    {
      "id": "cit_001",
      "document_name": "engineering-materials.pdf",
      "page_number": 12,
      "excerpt": "Martensite forms through...",
      "relevance_score": 0.92
    }
  ]
}

---

## Quiz Generation

### POST /quiz/generate
Generate quiz questions for a topic.

**Request:**
```json
{
  "topic": "Heat Treatment of Steel",
  "difficulty": "medium",
  "num_questions": 10,
  "question_types": ["mcq", "short_answer", "true_false"]
}

Field	Type	Required	Default	Description
topic	string	Yes	-	Topic to generate questions about
difficulty	string	No	"medium"	"easy", "medium", or "hard"
num_questions	int	No	10	Number of questions (1-50)
question_types	array	No	all types	Types to include

Response:

{
  "questions": [
    {
      "id": "q-001",
      "question": "What microstructure forms when steel is rapidly cooled from above the critical temperature?",
      "question_type": "mcq",
      "options": [
        "Pearlite",
        "Martensite",
        "Austenite",
        "Bainite"
      ],
      "correct_answer": "Martensite",
      "explanation": "Rapid cooling (quenching) prevents diffusion, causing austenite to transform to martensite through a shear mechanism.",
      "topic": "Heat Treatment of Steel",
      "difficulty": "medium",
      "cognitive_level": "application",
      "source_chunk_ids": ["e2dc90d3_0047", "e2dc90d3_0048"]
    }
  ],
  "metadata": {
    "generated_at": "2026-08-06T12:00:00Z",
    "model": "llama-3.3-70b-versatile",
    "tokens_used": 1523
  }
}

Flashcard Generation

POST /flashcards/generate

Generate flashcards for a topic.

Request:

{
  "topic": "Composite Materials",
  "difficulty": "medium",
  "num_cards": 15
}

Field	Type	Required	Default	Description
topic	string	Yes	-	Topic for flashcards
difficulty	string	No	null	"easy", "medium", "hard", or null (mixed)
num_cards	int	No	10	Number of cards (1-50)

Response:

{
  "flashcards": [
    {
      "id": "fc-001",
      "question": "Composite materials combine two or more materials to achieve ___",
      "answer": "combined strengths",
      "hint": "Think about why we combine materials",
      "mnemonic": "COMPosite = COMbined Powers",
      "related_topics": ["Matrix", "Reinforcement", "Fibers"],
      "difficulty": "easy",
      "source_chunk_ids": ["e2dc90d3_0180"]
    }
  ]
}

Revision Notes

POST /notes/generate

Generate hierarchical revision notes.

Request:

{
  "topic": "Corrosion"
}

Response:

{
  "topic": "Corrosion",
  "subtopics": [
    {
      "title": "Types of Corrosion",
      "key_points": [
        "Uniform corrosion affects entire surface evenly",
        "Galvanic corrosion occurs between dissimilar metals",
        "Pitting corrosion creates localized holes",
        "Crevice corrosion occurs in confined spaces"
      ],
      "importance": "high"
    }
  ],
  "key_terms": [
    "Oxidation: Loss of electrons by a metal",
    "Reduction: Gain of electrons",
    "Passivation: Protective oxide layer formation"
  ],
  "formulae": [
    "Corrosion rate = (K × W) / (A × T × D)",
    "where K=constant, W=weight loss, A=area, T=time, D=density"
  ],
  "mnemonics": [
    "OIL RIG: Oxidation Is Loss, Reduction Is Gain (of electrons)"
  ]
}

Solution Generation

POST /solution/generate

Generate a model answer for an exam question.

Request:

{
  "question": "Explain the process of heat treatment of steel and its effects on mechanical properties.",
  "topic": "Heat Treatment",
  "marks": 10
}

Field	Type	Required	Default	Description
question	string	Yes	-	The exam question
topic	string	Yes	-	Subject area
marks	int	No	5	Mark allocation (affects depth)

Response:

{
  "question": "Explain the process of heat treatment...",
  "marks": 10,
  "answer": "Heat treatment is a controlled process of heating and cooling metals to alter their physical and mechanical properties without changing their shape...",
  "marking_scheme": [
    "1 mark: Define heat treatment correctly",
    "1 mark: Mention controlled heating and cooling",
    "2 marks: Explain annealing process and purpose",
    "2 marks: Explain quenching and tempering",
    "2 marks: Describe effects on hardness and ductility",
    "2 marks: Provide relevant examples"
  ],
  "key_points": [
    "Definition of heat treatment",
    "Types: annealing, normalizing, quenching, tempering",
    "Effect on microstructure",
    "Effect on mechanical properties",
    "Industrial applications"
  ],
  "topic": "Heat Treatment"
}

Chat Tutor

POST /chat

Ask the AI tutor a question.

Request:

{
  "message": "What is the difference between annealing and normalizing?"
}

Response:

{
  "answer": "**Annealing** involves heating steel above the critical temperature and then cooling it slowly (usually in the furnace) [Source: e2dc90d3_0052]. This produces a soft, ductile microstructure.\n\n**Normalizing** also heats above the critical temperature but cools in still air [Source: e2dc90d3_0053]. This produces a finer grain structure and slightly higher strength than annealing.\n\nWould you like me to explain when you'd use each process?",
  "sources": ["e2dc90d3_0052", "e2dc90d3_0053", "e2dc90d3_0054"],
  "is_grounded": true
}

POST /chat/reset

Clear conversation history.

Response:

{
  "message": "Chat history cleared"
}

Additional Info

POST /additional-info

Generate real-world supplementary information.

Request:

{
  "topic": "Steel Alloys"
}

Response:

{
  "applications": [
    "Automotive body panels using high-strength low-alloy steel (Automotive Industry)",
    "Surgical instruments from martensitic stainless steel (Medical Devices)",
    "Bridge cables using high-carbon steel wire (Civil Engineering)"
  ],
  "industry_uses": [
    "Aerospace: Landing gear components require high-strength steel alloys",
    "Oil & Gas: Pipeline steels resist corrosion in harsh environments",
    "Tool Manufacturing: Tool steels maintain hardness at high temperatures"
  ],
  "common_mistakes": [
    "Confusing steel grades: Using wrong alloy designation → Component failure",
    "Incorrect heat treatment: Wrong temperature or cooling rate → Poor properties",
    "Ignoring carbon content: Assuming all steels weld the same → Cracking"
  ],
  "interview_questions": [
    "What is the difference between carbon steel and alloy steel? (Difficulty: basic)",
    "How does chromium content affect stainless steel properties? (Difficulty: intermediate)",
    "Design a heat treatment process for a gear requiring high surface hardness but tough core. (Difficulty: advanced)"
  ]
}

Mind Map

GET /mindmap/{topic}

Generate a mind map structure for visualization.

Response:

{
  "nodes": [
    {"id": "root", "label": "Steel Alloys", "level": 0},
    {"id": "n1", "label": "Carbon Steels", "level": 1},
    {"id": "n2", "label": "Alloy Steels", "level": 1},
    {"id": "n1a", "label": "Low Carbon (<0.3%)", "level": 2},
    {"id": "n1b", "label": "Medium Carbon", "level": 2},
    {"id": "n1c", "label": "High Carbon (>0.6%)", "level": 2}
  ],
  "edges": [
    {"source": "root", "target": "n1"},
    {"source": "root", "target": "n2"},
    {"source": "n1", "target": "n1a"},
    {"source": "n1", "target": "n1b"},
    {"source": "n1", "target": "n1c"}
  ]
}

Spaced Repetition

GET /review/due

Get flashcards due for review.

Response:

{
  "due_cards": [
    {
      "card_id": "fc-001",
      "question": "Martensite forms when steel is cooled ___",
      "due_date": "2026-08-06",
      "ease_factor": 2.5,
      "interval_days": 3
    }
  ],
  "total_due": 5,
  "reviewed_today": 12
}

POST /review/record

Record a review result.

Request:

{
  "card_id": "fc-001",
  "quality": 4
}

Quality	Meaning
0	Complete blackout
1	Incorrect, remembered after seeing answer
2	Incorrect, but answer seemed easy to recall
3	Correct with serious difficulty
4	Correct with hesitation
5	Perfect recall

Response:

{
  "card_id": "fc-001",
  "next_review": "2026-08-10",
  "new_interval": 4,
  "new_ease_factor": 2.6
}

Dashboard

GET /dashboard

Get comprehensive learning progress dashboard data.

Response:

{
  "streak": {
    "current_streak": 12,
    "longest_streak": 25,
    "total_cards_reviewed": 347
  },
  "overall": {
    "total_quizzes": 45,
    "total_topics": 8,
    "average_score": 78.5,
    "study_time_minutes": 420,
    "weak_count": 2,
    "strong_count": 5
  },
  "weekly": {
    "reviews_this_week": 34,
    "quizzes_this_week": 5,
    "total_this_week": 39
  },
  "monthly": {
    "reviews_this_month": 156,
    "quizzes_this_month": 23,
    "total_this_month": 179
  },
  "due_cards": {
    "today": 15,
    "this_week": 47,
    "this_month": 89,
    "card_ids_today": ["fc-001", "fc-002", "fc-003"]
  },
  "topic_mastery": [
    {
      "topic": "Heat Treatment",
      "mastery_percent": 95.0,
      "mastery_level": "mastered",
      "attempts": 12,
      "last_attempted": "2026-08-06T14:30:00Z"
    },
    {
      "topic": "Corrosion",
      "mastery_percent": 70.0,
      "mastery_level": "familiar",
      "attempts": 8,
      "last_attempted": "2026-08-05T10:15:00Z"
    }
  ],
  "heatmap": [
    {"date": "2026-08-01", "count": 5, "level": 2},
    {"date": "2026-08-02", "count": 12, "level": 4},
    {"date": "2026-08-03", "count": 0, "level": 0}
  ],
  "exam_readiness": {
    "score": 72.5,
    "level": "good",
    "message": "Good progress! Focus on weak topics to improve further.",
    "breakdown": {
      "mastery": 78.5,
      "consistency": 80.0,
      "coverage": 62.5,
      "recency": 57.1
    }
  },
  "learning_velocity": [
    {"week": "Week 1", "week_start": "2026-06-17", "average_score": 65.0, "quizzes": 3},
    {"week": "Week 2", "week_start": "2026-06-24", "average_score": 72.0, "quizzes": 4},
    {"week": "Week 8", "week_start": "2026-08-05", "average_score": 85.0, "quizzes": 5}
  ]
}

Dashboard Components:

Component	Description
`streak`	Current and longest streaks, total reviews
`overall`	Aggregate stats across all activity
`weekly/monthly`	Activity summaries for time periods
`due_cards`	Cards due for spaced repetition
`topic_mastery`	Per-topic progress with mastery levels
`heatmap`	Daily activity for GitHub-style calendar (365 days)
`exam_readiness`	Predicted readiness score (0-100) with breakdown
`learning_velocity`	Weekly score trends (8 weeks)

Exam Readiness Calculation:

40% — Average mastery across topics
30% — Consistency (streak factor, max at 30 days)
20% — Coverage (mastered topics / total topics)
10% — Recency (activity in last 7 days)

Mastery Levels:

Level	Average Score
`not_started`	No attempts
`learning`	< 60%
`familiar`	60-84%
`mastered`	≥ 85%

Heatmap Levels:

Level	Activity Count
0	0 activities
1	1-2 activities
2	3-5 activities
3	6-10 activities
4	11+ activities

POST /dashboard/record-review

Record a flashcard review with streak tracking.

Use this instead of /review/record to track reviews for dashboard metrics.

Request Parameters:

card_id (string): Flashcard ID
quality (int): Review quality 0-5

Response:

{
  "status": "success",
  "card_id": "fc-001",
  "quality": 4,
  "next_review": "2026-08-10",
  "interval_days": 4,
  "current_streak": 13
}

Error Responses

All endpoints may return these error formats:

400 Bad Request

{
  "detail": "topic is required"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "num_questions"],
      "msg": "ensure this value is less than or equal to 50",
      "type": "value_error.number.not_le"
    }
  ]
}

500 Internal Server Error

{
  "detail": "LLM generation failed after 3 retries"
}

Rate Limits

When using cloud LLM providers:

Groq: ~30 requests/minute (free tier)
OpenRouter: Varies by model

The API automatically handles rate limiting with retries and fallback.

WebSocket (Future)

Real-time streaming responses planned for:

/ws/chat — Streaming chat responses
/ws/progress — Real-time processing updates

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

NeuroForge API Reference

Table of Contents

Health & Status

GET /

GET /health

GET /stats

Subject Management

POST /subjects

GET /subjects

GET /subjects/{subject_id}

PUT /subjects/{subject_id}

DELETE /subjects/{subject_id}

POST /subjects/{subject_id}/archive

POST /subjects/{subject_id}/restore

GET /subjects/{subject_id}/documents

DELETE /subjects/{subject_id}/documents/{doc_id}

Document Management

POST /upload

GET /documents

GET /progress/{document_id}

Source Attribution (Citations)

Citation Object

GET /chunks/{chunk_id}/citation

POST /citations/batch

GET /subjects/{subject_id}/documents/{doc_id}/file

GET /subjects/{subject_id}/documents/{doc_id}/chunks

Citations in Generation Responses

Flashcard Generation

POST /flashcards/generate

Revision Notes

POST /notes/generate

Solution Generation

POST /solution/generate

Chat Tutor

POST /chat

POST /chat/reset

Additional Info

POST /additional-info

Mind Map

GET /mindmap/{topic}

Spaced Repetition

GET /review/due

POST /review/record

Dashboard

GET /dashboard

POST /dashboard/record-review

Error Responses

400 Bad Request

422 Validation Error

500 Internal Server Error

Rate Limits

WebSocket (Future)