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
```json
{
  "success": true,
  "data": { ... },
  "message": "optional",
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### Error Response
```json
{
  "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 |