API Endpoints Reference

This document provides a comprehensive reference of all API endpoints available in TalentG, organized by category with detailed parameter and response specifications.

API Architecture

Base URL

Production: https://talentg.vercel.app/api
Development: http://localhost:3000/api

Authentication

All API endpoints require authentication via Supabase JWT tokens:

Authorization: Bearer <supabase-jwt-token>

Response Format

All responses follow a consistent JSON structure:

{
  "success": boolean,
  "data": object | array | null,
  "error": string | null,
  "timestamp": string
}

Authentication & User Management

POST `/api/auth/create-profile`

Create or update user profile after authentication. Request Body:

{
  "firstName": "string",
  "lastName": "string",
  "role": "student" | "trainer" | "university" | "admin",
  "bio": "string?",
  "linkedinUrl": "string?",
  "githubUrl": "string?"
}

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "firstName": "string",
    "lastName": "string",
    "role": "string",
    "createdAt": "timestamp"
  }
}

POST `/api/profile-picture`

Upload and update user profile picture. Request: multipart/form-data

file: Image file (max 10MB, formats: JPG, PNG, WebP)

Response:

{
  "success": true,
  "data": {
    "avatarUrl": "string",
    "fileName": "string"
  }
}

POST `/api/user-avatar`

Synchronize user avatar across the system. Request Body:

{
  "userId": "uuid",
  "avatarUrl": "string"
}

Assessment System

POST `/api/assessments/save`

Save assessment results and trigger AI analysis. Request Body:

{
  "assessmentId": "uuid",
  "answers": [
    {
      "questionId": "string",
      "answer": "string | number | string[]",
      "score": number
    }
  ],
  "sectionScores": {
    "leadership": 75,
    "communication": 80,
    "problemSolving": 70
  }
}

Response:

{
  "success": true,
  "data": {
    "assessmentId": "uuid",
    "aiAnalysis": "string",
    "pdfUrl": "string?",
    "completedAt": "timestamp"
  }
}

GET `/api/assessments/[id]`

Retrieve assessment results by ID. Path Parameters:

id: Assessment UUID

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "userId": "uuid",
    "answers": "json",
    "sectionScores": "json",
    "aiSummary": "string",
    "pdfUrl": "string?",
    "createdAt": "timestamp",
    "completedAt": "timestamp?"
  }
}

POST `/api/generate-strength-analysis`

Generate AI-powered personality analysis. Request Body:

{
  "assessmentId": "uuid",
  "answers": "AssessmentAnswer[]",
  "userContext": {
    "name": "string",
    "category": "working_professional" | "student",
    "jobRole": "string?"
  }
}

Response:

{
  "success": true,
  "data": {
    "analysis": "string (400 words)",
    "keyInsights": "string[]",
    "recommendations": "string[]",
    "processingTime": number
  }
}

POST `/api/strength-finder-pdf`

Generate and download assessment PDF report. Request Body:

{
  "assessmentId": "uuid",
  "placeholders": {
    "user_name": "string",
    "strong_trait1": "string",
    "strong_trait1_score": "string",
    // ... additional placeholders
  }
}

Response:

{
  "success": true,
  "data": {
    "pdfUrl": "string",
    "fileName": "string",
    "expiresAt": "timestamp"
  }
}

Admin & Management

GET `/api/admin/users`

Retrieve paginated list of all users. Query Parameters:

page: number (default: 1)
limit: number (default: 50)
role: string (optional filter)
search: string (optional search)

Response:

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "uuid",
        "email": "string",
        "firstName": "string",
        "lastName": "string",
        "role": "string",
        "createdAt": "timestamp",
        "lastLogin": "timestamp?"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1000,
      "pages": 20
    }
  }
}

POST `/api/admin/manage-users`

Create, update, or deactivate user accounts. Request Body:

{
  "action": "create" | "update" | "deactivate",
  "userId": "uuid?", // Required for update/deactivate
  "userData": {
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "role": "string"
  }
}

Response:

{
  "success": true,
  "data": {
    "userId": "uuid",
    "action": "string",
    "updatedAt": "timestamp"
  }
}

GET `/api/admin/analytics`

Retrieve system-wide analytics and metrics. Query Parameters:

period: “day” | “week” | “month” | “year” (default: “month”)
metrics: string[] (optional filters)

Response:

{
  "success": true,
  "data": {
    "userStats": {
      "totalUsers": 1000,
      "activeUsers": 750,
      "newUsers": 50
    },
    "assessmentStats": {
      "totalAssessments": 500,
      "completedAssessments": 450,
      "averageCompletionTime": 900
    },
    "systemHealth": {
      "uptime": 99.9,
      "responseTime": 150,
      "errorRate": 0.1
    }
  }
}

POST `/api/trainer/manage-courses`

Create and manage training courses (Trainer role). Request Body:

{
  "action": "create" | "update" | "publish",
  "courseId": "uuid?", // Required for update/publish
  "courseData": {
    "title": "string",
    "description": "string",
    "category": "string",
    "difficulty": "beginner" | "intermediate" | "advanced",
    "duration": number,
    "modules": [
      {
        "title": "string",
        "content": "string",
        "order": number
      }
    ]
  }
}

GET `/api/universities/students`

Retrieve university student data and analytics. Query Parameters:

universityId: uuid
page: number
limit: number
status: “active” | “inactive” | “graduated”

Response:

{
  "success": true,
  "data": {
    "students": [
      {
        "id": "uuid",
        "name": "string",
        "email": "string",
        "enrollmentDate": "timestamp",
        "coursesCompleted": number,
        "averageGrade": number,
        "attendanceRate": number
      }
    ],
    "analytics": {
      "totalStudents": 500,
      "activeStudents": 450,
      "graduationRate": 85
    }
  }
}

POST `/api/manage-plans`

Manage subscription plans and user entitlements. Request Body:

{
  "action": "upgrade" | "downgrade" | "cancel",
  "userId": "uuid",
  "planType": "free" | "pro" | "enterprise",
  "features": ["ai_resume_chat", "interview_prep", "advanced_analytics"]
}

Content & Media

POST `/api/uploadthing/*`

File upload handling via UploadThing service. Request: multipart/form-data

file: File to upload
folder: Destination folder
metadata: Additional file metadata

Response:

{
  "success": true,
  "data": {
    "fileUrl": "string",
    "fileName": "string",
    "fileSize": number,
    "fileType": "string",
    "uploadedAt": "timestamp"
  }
}

POST `/api/storage/upload`

Direct file upload to Supabase Storage. Request: multipart/form-data

file: File to upload
bucket: Storage bucket name
path: File path within bucket

Response:

{
  "success": true,
  "data": {
    "fileUrl": "string",
    "filePath": "string",
    "fileId": "string"
  }
}

POST `/api/test-upload`

Test file upload functionality. Request: multipart/form-data

file: Test file

Response:

{
  "success": true,
  "data": {
    "message": "Upload test successful",
    "fileInfo": {
      "name": "string",
      "size": number,
      "type": "string"
    }
  }
}

Gamification & Analytics

GET `/api/leaderboard`

Retrieve leaderboard rankings and statistics. Query Parameters:

period: “daily” | “weekly” | “monthly” | “all-time”
category: “overall” | “assessments” | “courses” | “internships”
limit: number (default: 50)

Response:

{
  "success": true,
  "data": {
    "leaderboard": [
      {
        "rank": 1,
        "userId": "uuid",
        "name": "string",
        "avatarUrl": "string",
        "score": 2500,
        "category": "assessments",
        "change": 5 // Rank change from previous period
      }
    ],
    "userRank": {
      "rank": 15,
      "score": 1800,
      "percentile": 85
    }
  }
}

GET `/api/analytics/dashboard`

Retrieve personalized dashboard analytics. Query Parameters:

userId: uuid (required)
period: “week” | “month” | “quarter” | “year”

Response:

{
  "success": true,
  "data": {
    "userStats": {
      "assessmentsCompleted": 5,
      "coursesEnrolled": 3,
      "averageScore": 85,
      "studyStreak": 12
    },
    "recentActivity": [
      {
        "type": "assessment_completed",
        "title": "Strength Finder Assessment",
        "date": "timestamp",
        "score": 90
      }
    ],
    "achievements": [
      {
        "id": "first_assessment",
        "title": "First Assessment Completed",
        "unlockedAt": "timestamp"
      }
    ]
  }
}

GET `/api/important-dates`

Retrieve calendar events and important dates. Query Parameters:

userId: uuid
startDate: ISO date string
endDate: ISO date string
type: “assignment” | “class” | “deadline” | “event”

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "uuid",
        "title": "Assignment Due",
        "description": "Submit final project",
        "startDate": "timestamp",
        "endDate": "timestamp",
        "type": "assignment",
        "courseId": "uuid",
        "priority": "high"
      }
    ],
    "upcomingDeadlines": [
      {
        "title": "Final Exam",
        "dueDate": "timestamp",
        "daysLeft": 3
      }
    ]
  }
}

Communication

POST `/api/feedback/submit`

Submit feedback and reviews. Request Body:

{
  "type": "course" | "mentor" | "platform" | "bug_report",
  "targetId": "uuid?", // Course, mentor, or user ID
  "rating": number, // 1-5 stars
  "comment": "string",
  "category": "content" | "difficulty" | "support" | "technical"
}

Response:

{
  "success": true,
  "data": {
    "feedbackId": "uuid",
    "submittedAt": "timestamp",
    "status": "submitted"
  }
}

GET `/api/announcements`

Retrieve system announcements and notifications. Query Parameters:

userId: uuid
category: “general” | “academic” | “system” | “urgent”
unreadOnly: boolean
limit: number

Response:

{
  "success": true,
  "data": {
    "announcements": [
      {
        "id": "uuid",
        "title": "string",
        "content": "string",
        "category": "string",
        "priority": "low" | "medium" | "high" | "urgent",
        "createdAt": "timestamp",
        "readAt": "timestamp?"
      }
    ],
    "unreadCount": 3
  }
}

POST `/api/debug/log`

Submit debug information and error reports. Request Body:

{
  "type": "error" | "performance" | "feature_usage",
  "message": "string",
  "stackTrace": "string?",
  "userAgent": "string",
  "url": "string",
  "userId": "uuid?",
  "metadata": object
}

Response:

{
  "success": true,
  "data": {
    "logId": "uuid",
    "recordedAt": "timestamp"
  }
}

Error Handling

Common Error Responses

Authentication Error:

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED",
  "timestamp": "2025-01-28T10:00:00Z"
}

Permission Denied:

{
  "success": false,
  "error": "Insufficient permissions",
  "code": "PERMISSION_DENIED",
  "timestamp": "2025-01-28T10:00:00Z"
}

Validation Error:

{
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "timestamp": "2025-01-28T10:00:00Z"
}

Rate Limit Exceeded:

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT",
  "retryAfter": 60,
  "timestamp": "2025-01-28T10:00:00Z"
}

Rate Limiting

Rate Limit Headers

All API responses include rate limiting information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 3600

Rate Limits by Endpoint Category

Category	Limit	Window	Reset Behavior
Authentication	10 req/min	60s	Sliding window
Assessment	50 req/min	60s	Sliding window
File Upload	20 req/min	60s	Sliding window
Analytics	100 req/min	60s	Sliding window
Admin Operations	200 req/min	60s	Sliding window

Webhook Endpoints

POST `/api/webhooks/stripe`

Handle Stripe payment webhooks. Headers:

Stripe-Signature: t=1234567890,v1=signature...
Content-Type: application/json

POST `/api/webhooks/uploadthing`

Handle UploadThing file processing webhooks. Request Body: UploadThing webhook payload

{
  "type": "upload.complete",
  "data": {
    "fileUrl": "string",
    "fileName": "string",
    "fileSize": number
  }
}

API Versioning

Version Strategy

Current Version: v1 (implicit in base path)
Future Versions: /api/v2/ for breaking changes
Deprecation: 6-month deprecation period for breaking changes

Version Headers

Accept-Version: v1
API-Version: v1

Testing

API Testing Tools

Postman Collection: Available in /docs/api-reference/
Swagger UI: Interactive API documentation
cURL Examples: Provided for each endpoint

Test Environment

Base URL: http://localhost:3000/api
Test Data: Pre-populated test users and assessments
Rate Limiting: Disabled in development environment

This comprehensive API reference covers all endpoints available in TalentG, providing developers with complete specifications for integration and development.

Getting Started

Core APIs

Additional APIs

​API Endpoints Reference

​API Architecture

​Base URL

​Authentication

​Response Format

​Authentication & User Management

​POST /api/auth/create-profile

​POST /api/profile-picture

​POST /api/user-avatar

​Assessment System

​POST /api/assessments/save

​GET /api/assessments/[id]

​POST /api/generate-strength-analysis

​POST /api/strength-finder-pdf

​Admin & Management

​GET /api/admin/users

​POST /api/admin/manage-users

​GET /api/admin/analytics

​POST /api/trainer/manage-courses

​GET /api/universities/students

​POST /api/manage-plans

​Content & Media

​POST /api/uploadthing/*

​POST /api/storage/upload

​POST /api/test-upload

​Gamification & Analytics

​GET /api/leaderboard

​GET /api/analytics/dashboard

​GET /api/important-dates

​Communication

​POST /api/feedback/submit

​GET /api/announcements

​POST /api/debug/log

​Error Handling

​Common Error Responses

​Rate Limiting

​Rate Limit Headers

​Rate Limits by Endpoint Category

​Webhook Endpoints

​POST /api/webhooks/stripe

​POST /api/webhooks/uploadthing

​API Versioning

​Version Strategy

​Version Headers

​Testing

​API Testing Tools

​Test Environment

API Endpoints Reference

API Architecture

Base URL

Authentication

Response Format

Authentication & User Management

POST `/api/auth/create-profile`

POST `/api/profile-picture`

POST `/api/user-avatar`

Assessment System

POST `/api/assessments/save`

GET `/api/assessments/[id]`

POST `/api/generate-strength-analysis`

POST `/api/strength-finder-pdf`

Admin & Management

GET `/api/admin/users`

POST `/api/admin/manage-users`

GET `/api/admin/analytics`

POST `/api/trainer/manage-courses`

GET `/api/universities/students`

POST `/api/manage-plans`

Content & Media

POST `/api/uploadthing/*`

POST `/api/storage/upload`

POST `/api/test-upload`

Gamification & Analytics

GET `/api/leaderboard`

GET `/api/analytics/dashboard`

GET `/api/important-dates`

Communication

POST `/api/feedback/submit`

GET `/api/announcements`

POST `/api/debug/log`

Error Handling

Common Error Responses

Rate Limiting

Rate Limit Headers

Rate Limits by Endpoint Category

Webhook Endpoints

POST `/api/webhooks/stripe`

POST `/api/webhooks/uploadthing`

API Versioning

Version Strategy

Version Headers

Testing

API Testing Tools

Test Environment