docs: add comprehensive API endpoint catalog

[KGFCH2]

Related Issue

Closes #134

Summary

Documents request schemas and status response guidelines.

Changes Made

• Created docs/API.md.

[vercel]

@KGFCH2 is attempting to deploy a commit to the Kunal Verma's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

🚀 PR Received Successfully

Hello @KGFCH2,

Thank you for taking the initiative to contribute to this project.

Please ensure that your PR follows all project guidelines properly before requesting review.

⚠️ Important Instructions

• Maintain proper code quality and structure
• Do not make unnecessary changes/files
• Ensure responsiveness across devices
• Follow existing project conventions strictly
• Attach screenshots/videos for UI-related changes
• Resolve merge conflicts before requesting review
• Avoid AI-generated low quality PRs or copied implementations

📌 Mandatory for GSSoC'26 Participants

Joining the community group and announcement channel is compulsory for all contributors participating through GSSoC'26.

• Telegram Group: https://t.me/c/3991077814/1
• Telegram Channel: https://t.me/+g4esQdo-DyNlZWE1

Failure to follow contribution guidelines may lead to PR rejection.

We appreciate your effort and wish you a great open-source journey ahead. ✨

[coderabbitai]

Warning

Review limit reached

@KGFCH2, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 33 minutes and 1 second. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 73cda961-51b9-4006-b389-9d5312b6eb48

📥 Commits

Reviewing files that changed from the base of the PR and between 9390870 and 5e7eaba.

📒 Files selected for processing (1)

• docs/API.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[kunalverma2512]

@coderabbitai please check what this PR does and why and give full reasoning for our full codebase and is this contain each and everything and is ready to merge

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== PR `#135` Details ==="
gh pr view 135 --repo kunalverma2512/CodeLens

echo ""
echo "=== Related Issue `#134` ==="
gh issue view 134 --repo kunalverma2512/CodeLens

echo ""
echo "=== Files Changed in PR ==="
gh pr diff 135 --repo kunalverma2512/CodeLens

echo ""
echo "=== Repository Structure ==="
tree -L 4 --gitignore 2>/dev/null || find . -type f | grep -v node_modules | grep -v .git | sort

echo ""
echo "=== Existing Route/Endpoint Files ==="
fd -e js -e ts -e py -e rb -e go | grep -iE "(route|controller|handler|api|endpoint)" | head -50

echo ""
echo "=== Search for route definitions ==="
rg -n "router\.(get|post|put|patch|delete|use)|app\.(get|post|put|patch|delete|use)|@(Get|Post|Put|Patch|Delete|Router)" --type js --type ts -A 1 | head -100

echo ""
echo "=== PR Review Comments ==="
gh pr view 135 --repo kunalverma2512/CodeLens --comments

Length of output: 20197

---

---

@kunalverma2512 Here is a full, detailed assessment of PR #135 against the actual codebase.

---

📋 What This PR Does & Why

What: Creates docs/API.md — a new documentation file (129 lines) cataloguing API endpoint schemas with request/response examples.

Why: Issue #134 identified that developers had to manually read router source files to understand API payloads. A central reference would accelerate frontend integration.

---

🔍 Full Codebase vs. Documentation Gap Analysis

The server has 7 backend modules with ~27 registered endpoints. The PR documents only 5 endpoints, and 2 of those 5 are factually incorrect.

✅ Correctly Documented (3/27)

Endpoint	Status
POST /api/auth/register	✅ Correct
POST /api/auth/verify-otp	✅ Correct
POST /api/auth/login	✅ Correct

---

❌ Documented Incorrectly (Endpoint Doesn't Exist)

Documented in PR	Actual Route in Codebase
GET /api/codeforces/stats	❌ Does not exist. Real routes are /profile, /dashboard, /rating-history, etc.
POST /api/ai/review	❌ Does not exist. Real routes are GET /api/ai/insight/stream and GET /api/ai/dashboard-summary

---

🚫 Completely Missing Modules & Endpoints

Auth (/api/auth) — 6 routes missing:

POST  /api/auth/forgot-password
POST  /api/auth/reset-password
POST  /api/auth/resend-otp
GET   /api/auth/github/start
GET   /api/auth/github/connect
GET   /api/auth/github/callback

User (/api/user) — entire module missing:

GET    /api/user/profile
PUT    /api/user/profile
DELETE /api/user/profile

Codeforces (/api/codeforces) — entire module missing (8 routes):

POST   /api/codeforces/connect
POST   /api/codeforces/verify
DELETE /api/codeforces/disconnect
GET    /api/codeforces/profile
GET    /api/codeforces/rating-history
GET    /api/codeforces/submissions
GET    /api/codeforces/dashboard
POST   /api/codeforces/refresh

AI (/api/ai) — entire module missing:

GET  /api/ai/insight/stream
GET  /api/ai/dashboard-summary

GitHub (/api/github) — entire module missing (5 routes):

GET  /api/github/dashboard
GET  /api/github/profile
GET  /api/github/repos
GET  /api/github/contributions
GET  /api/github/activity

CP module (server/modules/cp/) — exists but not yet mounted in app.js; still worth documenting.

Tasks module (server/modules/tasks/) — exists but not yet mounted in app.js; still worth documenting.

Health check:

GET  /api/health

---

📊 Coverage Summary

pie title API Documentation Coverage
    "Correctly Documented" : 3
    "Incorrectly Documented" : 2
    "Completely Missing" : 22

Loading

Metric	Value
Total actual endpoints	~27
Correctly documented	3
Incorrectly documented	2
Completely missing	~22
Coverage	~11%

---

🚦 Merge Verdict: NOT ready to merge

Reasons:

1. Only ~11% coverage — most modules are entirely absent.
2. Inaccurate routes — GET /api/codeforces/stats and POST /api/ai/review don't match real server routes, which would mislead frontend developers.
3. Entire modules missing — user, github, cp, tasks, and most of codeforces and auth are undocumented.
4. No error response schemas documented (e.g., 400, 401, 404, 500 patterns).
5. No authentication header documented for protected routes in user, github, and codeforces modules.

Recommended actions before merging:

• Fix the incorrect endpoint paths (/api/codeforces/stats → actual profile/dashboard routes; POST /api/ai/review → actual stream/summary routes)
• Add all missing endpoints from auth, user, codeforces, ai, github, cp, and tasks modules
• Document which endpoints require Authorization: Bearer <token> header
• Add standard error response examples (401 Unauthorized, 400 Bad Request, etc.)

[kunalverma2512]

@KGFCH2 I want that you iterate again and write for each endpoint and content should be honest
Another thing is you have to attach loom video or video inside drive link showcasing you have runned this project successfully on your local and also show by going to each pages and make PR description well explained with all neccessary things to write and attach