feat(api): add /api/v1/search/v2 endpoint

[DevanshuNEU]

Search V2 API Endpoint

Closes #142

Endpoint

POST /api/v1/search/v2

Request

{
  "query": "authentication middleware",
  "repo_id": "uuid",
  "top_k": 10,
  "use_reranking": true
}

Response

{
  "results": [
    {
      "name": "authenticate_user",
      "qualified_name": "auth.middleware.authenticate_user",
      "file_path": "src/auth/middleware.py",
      "code": "def authenticate_user(request): ...",
      "signature": "def authenticate_user(request: Request) -> User",
      "language": "python",
      "score": 0.92,
      "line_start": 45,
      "line_end": 67,
      "summary": "Validates JWT token and returns authenticated user",
      "class_name": null
    }
  ],
  "query": "authentication middleware",
  "total": 10,
  "cached": false,
  "search_version": "v2"
}

API Versioning Strategy

All endpoints stay under /api/v1/*:

• /api/v1/search → V1 (file-level, basic)
• /api/v1/search/v2 → V2 (function-level, hybrid ranking)

"v2" is a feature version of search, not an API version bump. When Search V2 becomes stable and default, it will replace /api/v1/search.

Features

• Function-level results (not file-level)
• AI-generated summaries
• Hybrid ranking: BM25 + semantic + Cohere reranking
• Response caching (1hr TTL)
• Feature flag: SEARCH_V2_ENABLED

Files Changed

• backend/routes/search_v2.py (NEW)
• backend/main.py (register route)
• .env.example (add COHERE_API_KEY, SEARCH_V2_ENABLED)
• backend/tests/test_search_v2_route.py (NEW - 4 tests)

Testing

cd backend && python3 -m pytest tests/test_search_v2_route.py -v
# 4 passed ✅

DevOps

Add to production env:

COHERE_API_KEY=xxx
SEARCH_V2_ENABLED=true

[vercel]

@DevanshuNEU is attempting to deploy a commit to the Dev's projects Team on Vercel.

A member of the Team first needs to authorize it.

[DevanshuNEU]

✅ PR Review Complete - Ready to Merge

Endpoint verified: POST /api/v1/search/v2

Route Structure (Confirmed)

Router prefix:  /search
Endpoint:       /v2
main.py prefix: /api/v1
─────────────────────────
Final path:     /api/v1/search/v2 ✅

Files Changed

File	Change
backend/routes/search_v2.py	NEW - 96 lines
backend/main.py	Import + register router
.env.example	COHERE_API_KEY, SEARCH_V2_ENABLED
backend/tests/test_search_v2_route.py	NEW - 4 tests

Tests

4 passed ✅

---

📋 Next Steps After Merge

@kiran-devops (Kiran)

1. Add COHERE_API_KEY to Railway production env
2. Set SEARCH_V2_ENABLED=true
3. Cohere free tier: 10K requests/month (sufficient for launch)

@arjun-frontend (Arjun)

1. New endpoint ready: POST /api/v1/search/v2
2. Request/Response schema in PR description
3. Can start Epic Epic: Frontend v2 - Premium Redesign #109 (Frontend V2 redesign)
4. Feature flag check: Only show V2 UI when search_version: "v2" in response

@devanshu (Raj)

1. Merge this PR
2. Next: Issue feat(search): Add "Why this result?" explanations #71 - "Why this matched" explanations
3. Then: Help Arjun with frontend integration

---

🎯 Search V2 Backend Status: COMPLETE

PR	Feature	Status
#138	Function Chunking	✅ Merged
#139	AI Summaries	✅ Merged
#140	Hybrid Search + RRF	✅ Merged
#141	Rerank v4.0-fast	✅ Merged
#143	API Endpoint	🟡 Ready to merge

Total: 47 tests passing across all Search V2 modules

[DevanshuNEU]

PR Review Complete - Ready to Merge

Endpoint: POST /api/v1/search/v2

Router prefix:  /search
Endpoint:       /v2
main.py prefix: /api/v1
Final path:     /api/v1/search/v2

Tests: 4 passed

---

Next Steps After Merge

DevOps:

• Add COHERE_API_KEY to production env
• Set SEARCH_V2_ENABLED=true

Frontend:

• Endpoint ready: POST /api/v1/search/v2
• Schema in PR description

Backend:

• Issue feat(search): Add "Why this result?" explanations #71 - "Why this matched" explanations

---

Search V2 Backend Status

PR	Feature	Status
#138	Function Chunking	Merged
#139	AI Summaries	Merged
#140	Hybrid Search + RRF	Merged
#141	Rerank v4.0-fast	Merged
#143	API Endpoint	Ready to merge

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
opencodeintel	Ignored	Preview	Jan 5, 2026 0:37am