Projects/docs/CompleteAPIDocumentation.md

Complete API Documentation for IE Research Platform

This document covers all existing API endpoints (based on provided controllers) and planned/missing endpoints that should be implemented based on services and repositories.

Base URL: http://localhost:9092/api
Authentication: Bearer token (obtained from /auth/login). Include in Authorization: Bearer <token> header.
CSRF Protection: Required for state-changing methods (POST, PUT, DELETE). Include X-CSRF-Token header.

---

1. Authentication & User Management

Existing Endpoints (/api/auth, /api/users, /api/settings)

Method	Endpoint	Description	Auth
POST	/auth/register	Register new user	No
POST	/auth/login	Login → returns token + CSRF	No
POST	/auth/login/2fa	Verify 2FA code after login	No
POST	/auth/logout	Invalidate session	Yes
POST	/auth/refresh	Refresh access token	Yes
GET	/auth/me	Get current user profile	Yes
POST	/auth/forgot-password	Get security question	No
POST	/auth/reset-password	Reset password using answer	No
POST	/auth/change-password	Change password (authenticated)	Yes
GET/POST	/auth/verify-email	Verify email with token	No
POST	/auth/resend-verification	Resend verification email	No
GET	/users/me	Get current user	Yes
PUT	/users/me	Update profile	Yes
PUT	/users/me/password	Change password	Yes
DELETE	/users/me	Delete own account	Yes
GET	/users/{username}	Get public profile	No
GET	/users/{username}/is-following	Check if current user follows	Yes
POST	/users/{username}/follow	Follow user	Yes
DELETE	/users/{username}/follow	Unfollow user	Yes
GET	/users/{username}/followers	List followers (paginated)	Yes
GET	/users/{username}/following	List following (paginated)	Yes
GET	/users/search	Search users	Yes
GET	/users/me/bookmarks	Get user's bookmarked articles	Yes
POST/DELETE	/users/me/bookmarks/{articleId}	Add/remove bookmark	Yes
GET	/users/me/contacts	List followed users	Yes
POST	/users/me/avatar	Upload avatar (base64)	Yes
DELETE	/users/me/avatar	Remove avatar	Yes
POST	/users/2fa/enable	Generate 2FA secret + QR	Yes
POST	/users/2fa/verify	Verify and enable 2FA	Yes
POST	/users/2fa/disable	Disable 2FA	Yes
GET	/users/2fa/backup-codes	Get backup codes	Yes
GET	/users/me/analytics	Get personal analytics	Yes
GET	/users/me/settings	Get all settings	Yes
PUT	/users/me/settings	Update settings	Yes
PUT	/users/me/security	Update security question	Yes
PUT	/users/notifications	Update notification preferences	Yes

Missing Endpoints (to implement)

Method	Endpoint	Description	Priority
GET	/users/{username}/stats	Get user statistics (articles, followers, etc.)	Medium
GET	/users/{username}/activity	Get user activity feed (comments, likes, shares)	Medium
POST	/users/batch	Batch fetch user profiles (by IDs)	Low
PUT	/users/{id}/role	Admin – change user role	High
PUT	/users/{id}/status	Admin – activate/deactivate user	High
DELETE	/users/{id}	Admin – delete user	High
GET	/users/admin/all	Admin – list all users with pagination	High

---

2. Articles

Existing Endpoints (/api/articles)

Method	Endpoint	Description	Auth
GET	/articles	List all published articles	No
GET	/articles/{id}	Get article by ID (increments view)	No
POST	/articles	Create new article	Yes
PUT	/articles/{id}	Update own article	Yes
DELETE	/articles/{id}	Delete own article	Yes
GET	/articles/search	Search articles with filters	No
GET	/articles/trending	Get trending articles	No
GET	/articles/featured	Get featured articles	No
GET	/articles/discovery	Get popular articles	No
GET	/articles/tags	List all tags with counts	No
GET	/articles/tags/{tag}	Get articles by tag (paginated)	No
GET	/articles/{id}/like	Get like status	Yes
POST	/articles/{id}/like	Like article	Yes
DELETE	/articles/{id}/like	Unlike article	Yes
GET	/articles/{id}/bookmark	Check bookmark status	Yes
POST	/articles/{id}/bookmark	Bookmark article	Yes
DELETE	/articles/{id}/bookmark	Remove bookmark	Yes
GET	/articles/bookmarks	Get user's bookmarked articles	Yes
POST	/articles/{id}/publish	Publish draft article	Yes
GET	/articles/{id}/citation	Generate citation (APA, MLA, BibTeX)	No
GET	/articles/{id}/recommendations	Get related articles	No
GET	/articles/{id}/graph-recommendations	Get citation‑graph recommendations	No
GET	/articles/list	Paginated list with tag/search	No
GET	/articles/me/analytics	Author analytics	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/articles/drafts	Get current user's draft articles	High
GET	/articles/pending	Admin – get pending articles for approval	High
POST	/articles/{id}/approve	Admin – approve article	High
POST	/articles/{id}/reject	Admin – reject article with reason	High
POST	/articles/bulk-delete	Admin – delete multiple articles	Medium
GET	/articles/{id}/versions	Get version history	Medium
POST	/articles/{id}/restore/{version}	Restore previous version	Medium
GET	/articles/{id}/analytics	Detailed analytics (views over time, referrers)	Medium

---

3. Comments

Existing Endpoints (/api/comments)

Method	Endpoint	Description	Auth
GET	/comments/article/{articleId}	Get comments for article (paginated)	No
GET	/comments/user/{username}	Get user's comments	No
GET	/comments/{id}	Get single comment	No
POST	/comments/article/{articleId}	Add comment	Yes
PUT	/comments/{id}	Edit own comment	Yes
DELETE	/comments/{id}	Delete own comment	Yes
POST	/comments/{id}/like	Like comment	Yes
DELETE	/comments/{id}/like	Unlike comment	Yes
GET	/comments/{id}/replies	Get replies to comment	No

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/comments/{id}/pin	Admin – pin comment	Medium
POST	/comments/{id}/unpin	Admin – unpin comment	Medium
POST	/comments/moderate	Admin – bulk approve/reject	Medium
GET	/comments/reported	Admin – list reported comments	Low

---

4. Likes & Bookmarks

Existing Endpoints (/api/likes, /api/bookmarks)

Method	Endpoint	Description	Auth
POST	/likes/articles/{articleId}	Like article	Yes
DELETE	/likes/articles/{articleId}	Unlike article	Yes
GET	/likes/articles/{articleId}/status	Get like status	Yes
GET	/likes/my-likes	Get user's liked articles	Yes
GET	/likes/users/{username}/likes	Get user's liked articles (public)	No
GET	/likes/articles/{articleId}/likers	List users who liked article	No
POST	/likes/batch/status	Batch check like status	Yes
POST	/likes/batch/counts	Batch get like counts	Yes
GET	/bookmarks	Get user's bookmarks	Yes
POST	/bookmarks/{articleId}	Add bookmark	Yes
DELETE	/bookmarks/{articleId}	Remove bookmark	Yes
GET	/bookmarks/check/{articleId}	Check if bookmarked	Yes
POST	/bookmarks/batch/check	Batch check bookmark status	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/bookmarks/folders	Get bookmark folders	Low
POST	/bookmarks/folders	Create folder	Low
POST	/bookmarks/{id}/move/{folderId}	Move bookmark to folder	Low

---

5. Collections

Existing Endpoints (/api/collections)

Method	Endpoint	Description	Auth
GET	/collections	List user's collections	Yes
GET	/collections/{id}	Get collection by ID	Yes
POST	/collections	Create new collection	Yes
PUT	/collections/{id}	Update collection	Yes
DELETE	/collections/{id}	Delete collection	Yes
GET	/collections/{id}/articles	Get articles in collection	Yes
POST	/collections/{id}/articles	Add article to collection	Yes
DELETE	/collections/{id}/articles/{articleId}	Remove article from collection	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/collections/public	List public collections	Medium
POST	/collections/{id}/share	Generate shareable link	Low
POST	/collections/{id}/reorder	Reorder articles	Low

---

6. Groups & Messaging

Existing Endpoints (/api/groups, /api/messages, /api/contacts)

Groups

Method	Endpoint	Description	Auth
GET	/groups	List user's groups	Yes
POST	/groups	Create group	Yes
GET	/groups/{id}	Get group details	Yes
PUT	/groups/{id}	Update group	Yes
DELETE	/groups/{id}	Delete group (owner only)	Yes
POST	/groups/{id}/invite	Generate invite token	Yes
POST	/groups/join/{token}	Join via invite token	Yes
POST	/groups/{id}/leave	Leave group	Yes
GET	/groups/{id}/members	List members	Yes
POST	/groups/{id}/members	Add member	Yes
DELETE	/groups/{id}/members/{userId}	Remove member	Yes
POST	/groups/{id}/messages	Send message	Yes
GET	/groups/{id}/messages	Get messages (paginated)	Yes
PUT	/groups/{id}/messages/{msgId}	Edit message	Yes
DELETE	/groups/{id}/messages/{msgId}	Delete message	Yes
POST	/groups/{id}/pins/{msgId}	Pin message	Yes
DELETE	/groups/{id}/pins/{msgId}	Unpin message	Yes
GET	/groups/{id}/pins	Get pinned messages	Yes
POST	/groups/{id}/typing	Send typing indicator	Yes
GET	/groups/{id}/typing	Get typing users	Yes
POST	/groups/{id}/mute	Mute group	Yes
DELETE	/groups/{id}/mute	Unmute group	Yes

Private Messages (/api/messages)

Method	Endpoint	Description	Auth
GET	/messages/conversations	List conversations	Yes
GET	/messages/conversations/{otherUser}	Get conversation messages	Yes
POST	/messages/conversations/{otherUser}	Send message	Yes
PUT	/messages/{id}	Edit message	Yes
DELETE	/messages/{id}	Delete message	Yes
POST	/messages/conversations/{otherUser}/read	Mark all as read	Yes
GET	/messages/unread	Get total unread count	Yes
POST	/messages/conversations/{otherUser}/typing	Send typing indicator	Yes
GET	/messages/conversations/{otherUser}/typing	Check if other user typing	Yes
DELETE	/messages/conversations/{otherUser}	Delete entire conversation	Yes
GET	/messages/search	Search messages	Yes

Contacts (/api/contacts)

Method	Endpoint	Description	Auth
GET	/contacts	List followed users	Yes
GET	/contacts/{username}	Get contact details	Yes
GET	/contacts/search	Search users to follow	Yes
POST	/contacts/{username}	Follow user	Yes
DELETE	/contacts/{username}	Unfollow user	Yes
GET	/contacts/online	Get online contacts	Yes
GET	/contacts/status/{username}	Get user online status	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/groups/{id}/transfer	Transfer ownership	Medium
POST	/groups/{id}/admins/{userId}	Promote to admin	Medium
DELETE	/groups/{id}/admins/{userId}	Demote from admin	Medium
GET	/groups/{id}/search-messages	Search within group	Low
GET	/messages/archived	List archived conversations	Low
POST	/messages/conversations/{otherUser}/archive	Archive conversation	Low
POST	/messages/forward	Forward message(s)	Medium

---

7. Notifications

Existing Endpoints (/api/notifications)

Method	Endpoint	Description	Auth
GET	/notifications	List user notifications (paginated)	Yes
GET	/notifications/unread-count	Get unread count	Yes
GET	/notifications/{id}	Get single notification	Yes
PUT	/notifications/{id}/read	Mark as read	Yes
PUT	/notifications/read-all	Mark all as read	Yes
DELETE	/notifications/{id}	Delete notification	Yes
DELETE	/notifications/delete-all	Delete all notifications	Yes
DELETE	/notifications/delete-read	Delete read notifications	Yes
GET	/notifications/preferences	Get notification settings	Yes
PUT	/notifications/settings	Update settings	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/notifications/preferences/digest	Configure email digest frequency	Low
GET	/notifications/unread/by-type	Unread counts grouped by type	Low

---

8. Events & Calendar

Existing Endpoints (/api/events)

Method	Endpoint	Description	Auth
GET	/events	List events with filters	No
GET	/events/upcoming	Get upcoming events	No
GET	/events/trending	Get trending events	No
GET	/events/{id}	Get event details	No
POST	/events	Create event	Yes
PUT	/events/{id}	Update own event	Yes
DELETE	/events/{id}	Delete own event	Yes
POST	/events/{id}/attend	RSVP (attending/cancelled/waiting)	Yes
POST	/events/{id}/rsvp	Alternative RSVP (yes/maybe/no)	Yes
GET	/events/{id}/attendees	List attendees	Yes
GET	/events/{id}/stats	Get event statistics (organizer only)	Yes
POST	/events/{id}/go-live	Start live stream (organizer)	Yes
GET	/events/my-events	Get user's events (organized/attending)	Yes
GET	/events/search	Search events	No

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/events/{id}/reminders	Set reminder	Low
DELETE	/events/{id}/reminders/{reminderId}	Delete reminder	Low
GET	/events/{id}/ical	Export event as iCal	Medium
POST	/events/recurring	Create recurring event series	Medium

---

9. Polls

Existing Endpoints (/api/polls)

Method	Endpoint	Description	Auth
POST	/polls	Create poll	Yes
GET	/polls/{id}	Get poll details	Yes
POST	/polls/{id}/vote	Vote on poll	Yes
GET	/polls/{id}/results	Get poll results	Yes
POST	/polls/{id}/close	Close poll (creator)	Yes
DELETE	/polls/{id}	Delete poll (creator)	Yes
GET	/polls/group/{groupId}	List polls in group	Yes
GET	/polls/my-votes	Get user's votes	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/polls/{id}/reopen	Reopen closed poll (creator)	Low
PUT	/polls/{id}	Update poll (add/remove options)	Medium

---

10. Projects & Tasks

Existing Endpoints (/api/projects)

Method	Endpoint	Description	Auth
GET	/projects	List user's projects	Yes
POST	/projects	Create project	Yes
GET	/projects/{id}	Get project details	Yes
PUT	/projects/{id}	Update project	Yes
DELETE	/projects/{id}	Delete project	Yes
GET	/projects/{id}/members	List members	Yes
POST	/projects/{id}/members	Add member	Yes
PUT	/projects/{id}/members/{memberId}	Update member role	Yes
DELETE	/projects/{id}/members/{memberId}	Remove member	Yes
GET	/projects/{id}/tasks	List tasks	Yes
POST	/projects/{id}/tasks	Create task	Yes
GET	/projects/{projectId}/tasks/{taskId}	Get task	Yes
PUT	/projects/{projectId}/tasks/{taskId}	Update task	Yes
PATCH	/projects/{projectId}/tasks/{taskId}/move	Move task to another column	Yes
DELETE	/projects/{projectId}/tasks/{taskId}	Delete task	Yes
GET	/projects/{id}/outputs	List deliverables	Yes
POST	/projects/{id}/outputs	Add deliverable	Yes
DELETE	/projects/{id}/outputs/{outputId}	Delete deliverable	Yes
GET	/projects/search	Search projects	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/projects/{id}/timeline	Get project timeline (Gantt)	Low
POST	/projects/{id}/export	Export project as JSON/PDF	Medium
POST	/projects/{id}/templates	Apply template	Low

---

11. Tools Store

Existing Endpoints (/api/tools, /api/public/tools, /api/admin/tools)

Method	Endpoint	Description	Auth
GET	/public/tools	List public tools (no auth)	No
GET	/public/tools/{id}	Get public tool	No
GET	/public/tools/trending	Trending tools	No
GET	/public/tools/popular	Popular tools	No
GET	/public/tools/newest	Newest tools	No
GET	/public/tools/top-rated	Top rated tools	No
GET	/public/tools/categories	Get categories	No
GET	/public/tools/stats	Get tool store stats	No
GET	/tools	List public tools (authenticated)	Yes
POST	/tools	Create tool (multipart)	Yes
GET	/tools/{id}	Get tool (with user state)	Yes
PUT	/tools/{id}	Update tool (multipart)	Yes
DELETE	/tools/{id}	Delete tool	Yes
POST	/tools/{id}/like	Like tool	Yes
DELETE	/tools/{id}/like	Unlike tool	Yes
GET	/tools/{id}/state	Get user state for tool	Yes
POST	/tools/{id}/install	Install tool	Yes
DELETE	/tools/{id}/install	Uninstall tool	Yes
GET	/tools/{id}/download	Download tool code	Yes
GET	/tools/trending	Trending (auth)	Yes
GET	/tools/popular	Popular (auth)	Yes
GET	/tools/newest	Newest (auth)	Yes
GET	/tools/top-rated	Top rated (auth)	Yes
GET	/tools/mine	My tools	Yes
GET	/tools/installed	Installed tools	Yes
GET	/tools/stats	Tool stats (auth)	Yes
GET	/tools/categories	Categories (auth)	Yes
POST	/tools/{id}/reviews	Add review	Yes
GET	/tools/{id}/reviews	Get reviews	Yes
POST	/tools/{id}/reviews/{reviewId}/helpful	Mark review helpful	Yes
GET	/tool-reviews/user/{userId}	Get user reviews (own)	Yes
DELETE	/tool-reviews/{reviewId}	Delete review	Yes
GET	/admin/tools/all	Admin – list all tools	Admin
POST	/admin/tools/{id}/feature	Admin – set featured	Admin
DELETE	/admin/tools/{id}/force	Admin – force delete	Admin

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/tools/{id}/downloads	Get download count (public)	Low
GET	/tools/analytics	Author analytics for own tools	Medium
POST	/tools/{id}/versions	Upload new version	Medium
GET	/tools/{id}/versions	List versions	Medium

---

12. Blog System

Existing Endpoints (/api/blog)

Method	Endpoint	Description	Auth
GET	/blog/posts	Get published posts (paginated)	No
GET	/blog/posts/{slug}	Get post by slug	No
GET	/blog/featured	Featured posts	No
GET	/blog/trending	Trending posts	No
GET	/blog/popular	Popular posts	No
GET	/blog/posts/{postId}/related	Related posts	No
POST	/blog/posts	Create post	Yes
PUT	/blog/posts/{postId}	Update own post	Yes
DELETE	/blog/posts/{postId}	Delete own post	Yes
GET	/blog/my-posts	Get user's posts	Yes
POST	/blog/admin/posts/{postId}/approve	Admin approve	Admin
POST	/blog/admin/posts/{postId}/reject	Admin reject	Admin
GET	/blog/admin/pending	Admin – pending posts	Admin
POST	/blog/posts/{postId}/like	Like post	Yes
DELETE	/blog/posts/{postId}/like	Unlike post	Yes
GET	/blog/categories	List categories	No
GET	/blog/categories/{slug}	Get category	No
POST	/blog/categories	Create category (admin)	Admin
PUT	/blog/categories/{id}	Update category (admin)	Admin
DELETE	/blog/categories/{id}	Delete category (admin)	Admin
GET	/blog/tags	List tags	No
GET	/blog/tags/{slug}	Get tag	No
POST	/blog/tags	Create tag (admin)	Admin
PUT	/blog/tags/{id}	Update tag (admin)	Admin
DELETE	/blog/tags/{id}	Delete tag (admin)	Admin
GET	/blog/comments/post/{postId}	Get comments for post	No
POST	/blog/comments	Add comment	Yes
PUT	/blog/comments/{commentId}	Update own comment	Yes
DELETE	/blog/comments/{commentId}	Delete comment	Yes
POST	/blog/comments/admin/{commentId}/approve	Admin approve	Admin
POST	/blog/comments/admin/{commentId}/reject	Admin reject	Admin
POST	/blog/comments/{commentId}/like	Like comment	Yes
DELETE	/blog/comments/{commentId}/like	Unlike comment	Yes
POST	/blog/comments/admin/{commentId}/pin	Admin pin	Admin
GET	/blog/stats	Get blog statistics	No

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/blog/posts/bulk-delete	Admin – bulk delete posts	Low
GET	/blog/posts/analytics/{postId}	Author analytics for post	Medium
POST	/blog/posts/{postId}/schedule	Schedule publication	Low

---

13. Search & Recommendations

Existing Endpoints (/api/search, /api/recommendations)

Method	Endpoint	Description	Auth
GET	/search	Unified search (articles, users, tags, groups)	Yes
GET	/search/articles	Search articles with filters	Yes
GET	/search/users	Search users	Yes
GET	/search/collections	Search collections	Yes
GET	/search/tags	Search tags	Yes
GET	/search/suggestions	Autocomplete suggestions	Yes
GET	/search/trending	Trending search terms	Yes
GET	/recommendations/personalized	Personalized feed	Yes
GET	/recommendations/trending	Trending articles	No
GET	/recommendations/similar/{articleId}	Similar articles	No
GET	/recommendations/hybrid	Hybrid feed	Yes
GET	/recommendations/content-based	Content‑based feed	Yes
GET	/recommendations/collaborative	Collaborative feed	Yes
GET	/recommendations/suggested-users	Suggested users to follow	Yes
GET	/recommendations/suggested-by-interest	Users by interest	Yes
GET	/recommendations/by-category	Personalized by category	Yes
GET	/recommendations/trending-by-category	Trending by category	No
GET	/recommendations/by-tags	Articles by tags	No
POST	/recommendations/feedback	Record feedback	Yes
GET	/recommendations/history	Recommendation history	Yes
POST	/recommendations/refresh	Admin – refresh model	Admin
POST	/recommendations/retrain	Admin – full retrain	Admin
GET	/recommendations/stats	Admin – model stats	Admin
POST	/recommendations/reset	Admin – reset model	Admin

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/search/explain	Explain search ranking	Low
GET	/recommendations/trending/explain	Explain trending score	Low

---

14. Peer Review & Submissions

Existing Endpoints (/api/peer-review)

Method	Endpoint	Description	Auth
POST	/peer-review/submissions	Submit paper	Yes
GET	/peer-review/submissions	Admin – list all submissions	Admin
GET	/peer-review/submissions/my	Get user's submissions	Yes
GET	/peer-review/submissions/{id}	Get submission	Yes
PUT	/peer-review/submissions/{id}/assign	Admin – assign reviewer	Admin
PUT	/peer-review/submissions/{id}/status	Admin – update status	Admin
DELETE	/peer-review/submissions/{id}	Admin – delete	Admin
POST	/peer-review/reviews	Submit review	Yes
GET	/peer-review/reviews/submission/{submissionId}	Get reviews for submission	Yes
GET	/peer-review/reviews/my	Get my reviews	Yes
POST	/peer-review/reviewer-credentials	Save reviewer profile	Yes
GET	/peer-review/reviewer-credentials	Get my credentials	Yes
GET	/peer-review/reviewers	Admin – list reviewers	Admin
PUT	/peer-review/reviewers/{userId}/verify	Admin – verify reviewer	Admin
DELETE	/peer-review/reviewer-credentials	Delete credentials	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/peer-review/reviews/{reviewId}/recommend	Editor decision based on reviews	High
GET	/peer-review/submissions/{id}/reviews/summary	Get review summary	Medium
POST	/peer-review/submissions/{id}/revision	Upload revised manuscript	Medium
GET	/peer-review/submissions/public	List public accepted papers	Low

---

15. Admin & System

Existing Endpoints (/api/admin, /api/audit, /api/backup, /api/metrics, /api/health)

Method	Endpoint	Description	Auth
GET	/admin/dashboard/stats	Admin dashboard stats	Admin
GET	/admin/stats/users	User statistics	Admin
GET	/admin/stats/articles	Article statistics	Admin
GET	/admin/users	List users (paginated)	Admin
GET	/admin/users/{userId}	Get user details	Admin
PUT	/admin/users/{userId}/role	Update user role	Admin
PUT	/admin/users/{userId}/status	Activate/deactivate user	Admin
DELETE	/admin/users/{userId}	Delete user	Admin
GET	/admin/articles	List articles (paginated)	Admin
DELETE	/admin/articles/{articleId}	Delete article	Admin
PUT	/admin/articles/{articleId}/featured	Toggle featured	Admin
GET	/admin/groups	List all groups	Admin
DELETE	/admin/groups/{id}	Delete group	Admin
GET	/admin/conversations	List all conversations	Admin
DELETE	/admin/conversations/{id}	Delete conversation	Admin
GET	/admin/comments	List all comments	Admin
DELETE	/admin/comments/{id}	Delete comment	Admin
GET	/admin/activity	Recent activity log	Admin
GET	/admin/2fa/status	2FA adoption stats	Admin
GET	/admin/rag/documents	List RAG documents	Admin
GET	/admin/export/{type}	Export users/articles/comments as CSV	Admin
GET	/admin/export/all	Export all data as ZIP	Admin
GET	/system/info	System info (CPU, memory, OS)	Admin
POST	/system/clear-cache	Clear application cache	Admin
GET	/audit/logs	Get audit logs	Admin
GET	/audit/user/{username}	Get user activity	Admin
GET	/audit/stats/actions	Action statistics	Admin
GET	/audit/summary/daily	Daily activity summary	Admin
GET	/audit/export	Export audit logs (CSV/JSON)	Admin
DELETE	/audit/cleanup	Delete old logs	Admin
GET	/backup	List backups	Admin
POST	/backup	Create backup	Admin
GET	/backup/{backupId}	Get backup info	Admin
GET	/backup/{backupId}/download	Download backup	Admin
POST	/backup/{backupId}/restore	Restore backup	Admin
DELETE	/backup/{backupId}	Delete backup	Admin
GET	/backup/settings	Get backup settings	Admin
PUT	/backup/settings	Update backup settings	Admin
POST	/backup/schedule	Create scheduled backup	Admin
DELETE	/backup/schedule/{scheduleId}	Delete schedule	Admin
GET	/metrics/system	System metrics	Admin
GET	/metrics/database	Database metrics	Admin
GET	/metrics/cache	Cache metrics	Admin
GET	/metrics/requests	Request metrics	Admin
GET	/metrics/users	User metrics	Admin
GET	/metrics/api-usage	API usage metrics	Admin
GET	/metrics/performance	Performance metrics	Admin
GET	/metrics/export	Export metrics (JSON/CSV)	Admin
GET	/health	Health check	No
GET	/health/details	Detailed health (admin)	Admin
GET	/health/ready	Readiness probe	No
GET	/health/live	Liveness probe	No

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/admin/stats/export	Export full statistics as Excel	Medium
POST	/admin/maintenance	Enable/disable maintenance mode	Low
GET	/admin/threads	Get thread dump	Low

---

16. Data Hub (Research Objects, Protocols, Preregistrations)

Existing Endpoints (/api/datahub)

Method	Endpoint	Description	Auth
GET	/datahub/research-objects	List research objects	Yes
GET	/datahub/research-objects/my	User's objects	Yes
GET	/datahub/research-objects/public	Public objects	Yes
GET	/datahub/research-objects/{id}	Get object	Yes
POST	/datahub/research-objects	Create object	Yes
PUT	/datahub/research-objects/{id}	Update object	Yes
DELETE	/datahub/research-objects/{id}	Delete object	Yes
GET	/datahub/research-objects/{id}/download	Download object	Yes
GET	/datahub/protocols	List protocols	Yes
GET	/datahub/protocols/my	User's protocols	Yes
GET	/datahub/protocols/public	Public protocols	Yes
GET	/datahub/protocols/{id}	Get protocol	Yes
POST	/datahub/protocols	Create protocol	Yes
PUT	/datahub/protocols/{id}	Update protocol	Yes
DELETE	/datahub/protocols/{id}	Delete protocol	Yes
POST	/datahub/protocols/{id}/fork	Fork protocol	Yes
GET	/datahub/protocols/{id}/steps	List steps	Yes
POST	/datahub/protocols/{id}/steps	Add step	Yes
PUT	/datahub/protocols/{protocolId}/steps/{stepId}	Update step	Yes
PATCH	/datahub/protocols/{protocolId}/steps/{stepId}/complete	Mark step complete	Yes
DELETE	/datahub/protocols/{protocolId}/steps/{stepId}	Delete step	Yes
GET	/datahub/preregistrations	List preregistrations (admin)	Admin
GET	/datahub/preregistrations/my	User's preregistrations	Yes
GET	/datahub/preregistrations/{id}	Get preregistration	Yes
POST	/datahub/preregistrations	Create preregistration	Yes
PUT	/datahub/preregistrations/{id}	Update	Yes
PUT	/datahub/preregistrations/{id}/sections/{sectionId}	Update section content	Yes
POST	/datahub/preregistrations/{id}/submit	Submit for registration	Yes
DELETE	/datahub/preregistrations/{id}	Delete	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/datahub/preregistrations/templates	List available templates	Medium
POST	/datahub/research-objects/validate	Validate before publish	Low
POST	/datahub/protocols/{id}/export	Export as PDF/LaTeX	Medium

---

17. Gap Analysis & Graph

Existing Endpoints (/api/gap-analysis)

Method	Endpoint	Description	Auth
GET	/gap-analysis/nodes	List all nodes	Yes
GET	/gap-analysis/nodes/{id}	Get node	Yes
POST	/gap-analysis/nodes	Create node	Yes
PUT	/gap-analysis/nodes/{id}	Update node	Yes
DELETE	/gap-analysis/nodes/{id}	Delete node (admin)	Admin
GET	/gap-analysis/nodes/search	Search nodes	Yes
GET	/gap-analysis/nodes/type/{type}	Get nodes by type	Yes
GET	/gap-analysis/edges	List edges	Yes
GET	/gap-analysis/edges/{id}	Get edge	Yes
POST	/gap-analysis/edges	Create edge	Yes
PUT	/gap-analysis/edges/{id}	Update edge	Yes
DELETE	/gap-analysis/edges/{id}	Delete edge (admin)	Admin
GET	/gap-analysis/edges/for-node/{nodeId}	Get edges for node	Yes
GET	/gap-analysis/edges/type/{type}	Get edges by type	Yes
GET	/gap-analysis/stats	Graph statistics	Yes
GET	/gap-analysis/node-degrees	Node degree map	Yes
GET	/gap-analysis/analyze/{gapId}	Analyze a gap	Yes
GET	/gap-analysis/hypothesis/{gapId}	Generate hypothesis	Yes
GET	/gap-analysis/export	Export graph as JSON (admin)	Admin
POST	/gap-analysis/import	Import graph (admin)	Admin
GET	/gap-analysis/path	Shortest path between nodes	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/gap-analysis/nodes/batch	Batch create nodes	Low
POST	/gap-analysis/edges/batch	Batch create edges	Low
GET	/gap-analysis/nodes/neighbors/{id}	Get neighbor nodes	Medium

---

18. Integrations & Webhooks

Existing Endpoints (/api/integrations, /api/webhooks)

Method	Endpoint	Description	Auth
GET	/integrations	List available integrations	Yes
GET	/integrations/my	List user's connected integrations	Yes
POST	/integrations/zotero/connect	Connect Zotero	Yes
GET	/integrations/zotero/collections	Get Zotero collections	Yes
GET	/integrations/zotero/items	Get Zotero items	Yes
POST	/integrations/zotero/import	Import from Zotero	Yes
POST	/integrations/mendeley/connect	Connect Mendeley	Yes
GET	/integrations/mendeley/documents	Get Mendeley documents	Yes
POST	/integrations/orcid/connect	Connect ORCID	Yes
GET	/integrations/orcid/works	Get ORCID works	Yes
POST	/integrations/googlescholar/connect	Connect Google Scholar	Yes
POST	/integrations/github/connect	Connect GitHub	Yes
GET	/integrations/github/repos	Get GitHub repos	Yes
DELETE	/integrations/{integrationId}	Disconnect integration	Yes
GET	/webhooks	List webhooks (admin)	Admin
POST	/webhooks	Create webhook (admin)	Admin
GET	/webhooks/{id}	Get webhook (admin)	Admin
PUT	/webhooks/{id}	Update webhook (admin)	Admin
DELETE	/webhooks/{id}	Delete webhook (admin)	Admin
POST	/webhooks/{id}/test	Test webhook (admin)	Admin
GET	/webhooks/{id}/logs	Get webhook logs (admin)	Admin
POST	/webhooks/receive/{token}	Public webhook receiver	No

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/integrations/crossref/import	Import from CrossRef by DOI	Medium
GET	/integrations/sync	Trigger manual sync for all integrations	Low
DELETE	/integrations/cache	Clear integration cache	Low

---

19. Reporting & Export

Existing Endpoints (/api/reports, /api/export)

Method	Endpoint	Description	Auth
GET	/reports/my-activity	User activity report	Yes
GET	/reports/my-content	User content report	Yes
GET	/reports/admin/daily	Daily report (admin)	Admin
GET	/reports/admin/weekly	Weekly report (admin)	Admin
GET	/reports/admin/monthly	Monthly report (admin)	Admin
GET	/reports/admin/yearly	Yearly report (admin)	Admin
GET	/reports/admin/top-articles	Top articles (admin)	Admin
GET	/reports/admin/top-authors	Top authors (admin)	Admin
GET	/reports/admin/top-tags	Top tags (admin)	Admin
GET	/reports/export/csv	Export report as CSV	Yes
GET	/reports/export/pdf	Export report as PDF	Yes
GET	/export/articles	Export articles (CSV, JSON, PDF)	Yes
GET	/export/collections	Export collections	Yes
GET	/export/references	Export references (BibTeX, CSV)	Yes
GET	/export/profile	Export user profile (JSON)	Yes
GET	/export/data	Export all data as ZIP	Yes
POST	/export/bibliography	Export bibliography from list	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
GET	/export/analytics	Export user analytics (JSON/CSV)	Medium
GET	/export/admin/audit	Admin – export audit logs	Medium

---

20. Utility & Miscellaneous

Existing Endpoints (/api/faq, /api/support, /api/newsletter, /api/invites, /api/citations, /api/uploads)

Method	Endpoint	Description	Auth
GET	/faq	List FAQs	No
GET	/faq/{id}	Get FAQ by ID	No
GET	/faq/categories	Get FAQ categories	No
GET	/faq/popular	Popular FAQs	No
POST	/faq	Admin – create FAQ	Admin
PUT	/faq/{id}	Admin – update FAQ	Admin
DELETE	/faq/{id}	Admin – delete FAQ	Admin
PUT	/faq/reorder	Admin – reorder FAQs	Admin
POST	/faq/bulk	Admin – bulk delete	Admin
POST	/support/tickets	Create support ticket	Yes
GET	/support/tickets	List my tickets	Yes
GET	/support/tickets/{ticketId}	Get ticket details	Yes
POST	/support/tickets/{ticketId}/replies	Add reply	Yes
POST	/support/tickets/{ticketId}/close	Close ticket	Yes
POST	/support/tickets/{ticketId}/reopen	Reopen ticket	Yes
GET	/support/admin/tickets	Admin – list all tickets	Admin
PUT	/support/admin/tickets/{ticketId}/status	Admin – update status	Admin
PUT	/support/admin/tickets/{ticketId}/assign	Admin – assign agent	Admin
POST	/support/admin/tickets/{ticketId}/notes	Admin – add internal note	Admin
GET	/support/admin/stats	Admin – support stats	Admin
POST	/newsletter/subscribe	Subscribe to newsletter	No
POST	/newsletter/unsubscribe	Unsubscribe	No
GET	/newsletter/status	Check subscription status	No
POST	/newsletter/send	Admin – send newsletter	Admin
GET	/newsletter/subscribers	Admin – list subscribers	Admin
GET	/newsletter/history	Admin – newsletter history	Admin
POST	/newsletter/preview	Admin – preview newsletter	Admin
POST	/invites/create	Create invite (logged in user)	Yes
GET	/invites/my-invites	List my invites	Yes
GET	/invites/sent	List sent invites	Yes
POST	/invites/{inviteId}/resend	Resend invite	Yes
DELETE	/invites/{inviteId}	Cancel invite	Yes
POST	/invites/accept/{token}	Accept invite (public)	No
GET	/invites/status/{token}	Get invite status (public)	No
GET	/citations/article/{articleId}	Get citation by format	No
POST	/citations/extract/doi	Extract metadata from DOI	Yes
POST	/uploads/image	Upload image (multipart)	Yes
POST	/uploads/document	Upload document	Yes

Missing Endpoints

Method	Endpoint	Description	Priority
POST	/uploads/avatar	Avatar upload (alias)	Already exists in /users/me/avatar
GET	/faq/search	Search FAQs	Low
GET	/support/tickets/statistics	User's own ticket stats	Medium
POST	/newsletter/templates	Admin – manage email templates	Low

---

21. Planned / Missing APIs (Not Implemented Yet)

Based on existing services and repositories without controllers:

Module	Method	Endpoint	Description	Priority
Grants	GET	/api/grants	List grants (public)	Medium
	GET	/api/grants/upcoming	Upcoming deadlines	Medium
	POST	/api/grants	Add grant (admin)	High
	PUT	/api/grants/{id}	Update grant	High
	DELETE	/api/grants/{id}	Delete grant	High
	GET	/api/grants/my	User's saved grants	Medium
	POST	/api/grants/{id}/apply	Mark as applied	Medium
Preprints	GET	/api/preprints	List preprints	No
	GET	/api/preprints/{id}	Get preprint	No
	POST	/api/preprints	Submit preprint	Yes
	PUT	/api/preprints/{id}	Update preprint	Yes
	DELETE	/api/preprints/{id}	Delete preprint	Yes
	POST	/api/preprints/{id}/publish	Publish preprint	Yes
	POST	/api/preprints/{id}/withdraw	Withdraw preprint	Yes
	GET	/api/preprints/my	User's preprints	Yes
	POST	/api/preprints/{id}/review	Start peer review	Admin
Provenance	GET	/api/provenance/entity/{entityId}	Get events for entity	Yes
	POST	/api/provenance/events	Add provenance event	Yes
	DELETE	/api/provenance/events/{eventId}	Delete event	Yes
Media	GET	/api/media	List user's media	Yes
	GET	/api/media/{id}	Get media metadata	Yes
	POST	/api/media	Upload media	Yes
	DELETE	/api/media/{id}	Delete media	Yes
Broadcast	GET	/api/broadcast/channels	List channels	No
	POST	/api/broadcast/channels	Create channel	Yes
	GET	/api/broadcast/channels/{id}/posts	List posts	No
	POST	/api/broadcast/posts	Create post	Yes
Workspace Panels	GET	/api/workspace/panels	List panels	Yes
	POST	/api/workspace/panels	Create panel	Yes
	PUT	/api/workspace/panels/{id}	Update panel	Yes
	DELETE	/api/workspace/panels/{id}	Delete panel	Yes
Encryption Keys	POST	/api/encryption/keys	Upload public keys	Yes (internal)
	GET	/api/encryption/keys/{conversationId}	Get keys for conversation	Yes
Citations Graph	GET	/api/citation-graph/article/{articleId}	Get node details	No
	GET	/api/citation-graph/network/{articleId}	Get neighbors	No
Tools Store State	GET	/api/tools-state	Get store state (snapshot)	Admin
	POST	/api/tools-state/refresh	Refresh snapshot	Admin

---

Authentication & Error Codes

Authentication Headers

• Authorization: Bearer <token> – required for all authenticated endpoints.
• X-CSRF-Token: <csrf> – required for POST, PUT, DELETE (obtained from login response).

Standard Response Format

{
  "success": true,
  "data": { ... },
  "message": "optional",
  "timestamp": "2024-01-01T12:00:00Z"
}

Error Response

{
  "success": false,
  "error": "Human‑readable message",
  "code": "ERROR_CODE",
  "timestamp": "..."
}

Common Error Codes

Code	HTTP Status	Meaning
UNAUTHORIZED	401	Missing or invalid token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
BAD_REQUEST	400	Invalid input
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error