feat(api): URL prefix versioning /api/v1 and /api/v2 (#737)

[ajianaz]

Summary

Adds URL prefix API versioning to uteke-server so breaking changes can be isolated behind version-specific routes.

Design

/api/v1/recall   → v1 format (flat: [{id, content, score, ...}])
/api/v2/recall   → v2 format (wrapped: [{memory: {id, content, ...}, score}])
/recall          → alias → latest (v2)
/health          → unversioned, returns api_versions + api_latest

Changes

Server (uteke-server)

• ApiVersion enum (V1, V2) with path prefix parser
• /api/v1/* routes → v1 response format (backward compat)
• /api/v2/* routes → current v2 response format
• Unversioned routes continue to work (alias to latest)
• HealthResponse now includes api_versions and api_latest
• to_v1_flat() adapter converts UnifiedSearchResult → flat v1 format

v1 vs v2 Response Format

Feature	v1 (v0.7.x compat)	v2 (v0.8.x+)
Recall response	Flat: [{id, content, score, namespace, tags}]	Wrapped: [{memory: {id, content, ...}, score}]

Implementation Notes

• Path prefix parsing is O(1) — no regex, just string stripping
• Read-only auth check uses stripped path — works for both /recall and /api/v1/recall
• All existing routes work unversioned (no breaking change for current consumers)
• Future breaking changes bump to v3, v1 gets deprecated per lifecycle in feat(api): URL prefix versioning (/api/v1, /api/v2) for breaking change isolation #737

Closes #737

[github-actions]

🔍 Cora AI Code Review

✅ No issues found. Code looks good!

---

Review powered by cora-cli · BYOK · MIT