Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
315 lines (252 loc) · 5.98 KB

API_DOCUMENTATION.md

File metadata and controls

315 lines (252 loc) · 5.98 KB

API Documentation - Gemini AI & College Scorecard Integration

Base URL

http://localhost:5001

All endpoints require Clerk authentication. Include the authentication token in your request headers.

AI Insights Endpoints

1. Analyze Student Profile

POST /api/ai-insights/analyze/:studentId

Generates comprehensive AI insights about a student including strengths, areas for growth, college readiness, and career recommendations.

Response:

{
  "success": true,
  "studentId": "...",
  "studentName": "...",
  "insights": {
    "overallAssessment": "...",
    "strengths": ["...", "..."],
    "areasForGrowth": ["...", "..."],
    "collegeReadinessScore": { "score": 8, "justification": "..." },
    "recommendedActions": ["...", "..."],
    "potentialCareers": ["...", "..."]
  },
  "generatedAt": "2026-01-24T..."
}

2. Generate College Recommendations (AI-Powered)

POST /api/ai-insights/college-recommendations/:studentId

Uses Gemini AI to analyze colleges and provide personalized recommendations with detailed reasoning.

Request Body (optional):

{
  "collegeList": [] // Optional: provide specific colleges to analyze
}

Response:

{
  "success": true,
  "studentId": "...",
  "recommendations": [
    {
      "collegeName": "...",
      "matchScore": 9,
      "reasoning": "...",
      "highlights": ["...", "..."]
    }
  ]
}

3. Predict Growth Trajectory

POST /api/ai-insights/growth-trajectory/:studentId

Analyzes student's historical milestones and predicts future development with suggested next steps.

Response:

{
  "success": true,
  "predictions": {
    "trajectoryAnalysis": "...",
    "predictedOutcomes": ["...", "..."],
    "suggestedMilestones": [
      {
        "title": "...",
        "description": "...",
        "timeframe": "3 months",
        "category": "Academic"
      }
    ],
    "riskFactors": ["..."],
    "accelerationOpportunities": ["..."]
  }
}

4. Batch Analyze Students

POST /api/ai-insights/batch-analyze

Analyze multiple students at once for dashboard overview.

Request Body:

{
  "studentIds": ["id1", "id2", "id3"]
}

College Search Endpoints

1. Search Colleges

GET /api/colleges/search

Search for colleges by name, state, size, etc.

Query Parameters:

  • name - College name (partial match)
  • state - Two-letter state code (e.g., "CA", "NY")
  • minSize - Minimum enrollment size
  • maxSize - Maximum enrollment size
  • page - Page number (default: 0)
  • perPage - Results per page (default: 20)

Example:

GET /api/colleges/search?state=CA&minSize=5000&maxSize=20000

2. Get College Details

GET /api/colleges/:collegeId

Get detailed information about a specific college.

Example:

GET /api/colleges/123456

3. Get Colleges by State

GET /api/colleges/state/:state

Get all colleges in a specific state.

Query Parameters:

  • page - Page number (default: 0)
  • perPage - Results per page (default: 20)

Example:

GET /api/colleges/state/TX?page=0&perPage=50

4. Match Colleges for Student

POST /api/colleges/match/:studentId

Find colleges that match a student's academic profile (GPA, estimated SAT, etc.).

Response:

{
  "success": true,
  "matchedColleges": [
    {
      "school.name": "...",
      "school.city": "...",
      "school.state": "...",
      "matchScore": 8,
      "admissions.admission_rate.overall": 0.45,
      "latest.admissions.sat_scores.average.overall": 1250
    }
  ],
  "matchCriteria": {
    "estimatedSAT": 1280,
    "gpaRange": "3.3 - 4.3"
  }
}

5. Quick Recommendations

GET /api/colleges/recommendations/:studentId

Get categorized college recommendations (reach, target, safety) without AI analysis for faster results.

Response:

{
  "success": true,
  "recommendations": {
    "reach": [...],
    "target": [...],
    "safety": [...]
  },
  "summary": {
    "totalMatches": 50,
    "reachCount": 12,
    "targetCount": 25,
    "safetyCount": 13
  }
}

6. Compare Colleges

POST /api/colleges/compare

Compare multiple colleges side by side.

Request Body:

{
  "collegeIds": [123456, 234567, 345678]
}

Response:

{
  "success": true,
  "colleges": [...],
  "comparison": {
    "admissionRates": [...],
    "tuitionCosts": [...],
    "sizes": [...]
  }
}

Integration Example (Frontend)

// Example: Analyze a student
const analyzeStudent = async (studentId) => {
  try {
    const response = await fetch(
      `http://localhost:5001/api/ai-insights/analyze/${studentId}`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${clerkToken}`
        }
      }
    );
    
    const data = await response.json();
    console.log(data.insights);
  } catch (error) {
    console.error('Error:', error);
  }
};

// Example: Search colleges
const searchColleges = async (state) => {
  try {
    const response = await fetch(
      `http://localhost:5001/api/colleges/search?state=${state}`,
      {
        headers: {
          'Authorization': `Bearer ${clerkToken}`
        }
      }
    );
    
    const data = await response.json();
    console.log(data.colleges);
  } catch (error) {
    console.error('Error:', error);
  }
};

Environment Variables Required

Ensure your .env file contains:

GEMINI_API_KEY=your_gemini_api_key
COLLEGE_SCORECARD_API_KEY=your_college_scorecard_api_key
MONGODB_URI=your_mongodb_connection_string
CLERK_SECRET_KEY=your_clerk_secret

Testing the Endpoints

Start the server:

npm run server

The server will run on http://localhost:5001

Test the health endpoint:

curl http://localhost:5001/api/health

Test AI analysis (requires authentication and valid student ID):

curl -X POST http://localhost:5001/api/ai-insights/analyze/YOUR_STUDENT_ID \
  -H "Authorization: Bearer YOUR_TOKEN"