diff --git a/veza-backend-api/internal/elasticsearch/search_service_test.go b/veza-backend-api/internal/elasticsearch/search_service_test.go
index 3c61d5840..b667cf270 100644
--- a/veza-backend-api/internal/elasticsearch/search_service_test.go
+++ b/veza-backend-api/internal/elasticsearch/search_service_test.go
@@ -8,7 +8,7 @@ import (
 
 func TestSearchService_Search_NilClient(t *testing.T) {
 	svc := NewSearchService(nil, zap.NewNop())
-	_, err := svc.Search("test", nil)
+	_, err := svc.Search("test", nil, nil)
 	if err == nil {
 		t.Fatal("expected error when client is nil")
 	}
diff --git a/veza-backend-api/internal/handlers/announcement_handler.go b/veza-backend-api/internal/handlers/announcement_handler.go
index 248c3c3f4..161d802a7 100644
--- a/veza-backend-api/internal/handlers/announcement_handler.go
+++ b/veza-backend-api/internal/handlers/announcement_handler.go
@@ -20,6 +20,15 @@ func NewAnnouncementHandler(svc *services.AnnouncementService) *AnnouncementHand
 }
 
 // List returns all announcements (admin)
+// @Summary List all announcements
+// @Description Get a list of all announcements, including expired ones. Admin only.
+// @Tags Admin
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} object{announcements=array}
+// @Failure 401 {object} handlers.APIResponse "Unauthorized"
+// @Router /api/v1/announcements [get]
 func (h *AnnouncementHandler) List(c *gin.Context) {
 	list, err := h.svc.List(c.Request.Context())
 	if err != nil {
@@ -30,6 +39,16 @@ func (h *AnnouncementHandler) List(c *gin.Context) {
 }
 
 // Create creates an announcement (admin)
+// @Summary Create announcement
+// @Description Create a new platform announcement. Admin only.
+// @Tags Admin
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param announcement body services.CreateAnnouncementRequest true "Announcement data"
+// @Success 201 {object} models.Announcement
+// @Failure 401 {object} handlers.APIResponse "Unauthorized"
+// @Router /api/v1/announcements [post]
 func (h *AnnouncementHandler) Create(c *gin.Context) {
 	userID, ok := GetUserIDUUID(c)
 	if !ok || userID == uuid.Nil {
@@ -52,6 +71,16 @@ func (h *AnnouncementHandler) Create(c *gin.Context) {
 }
 
 // Delete deletes an announcement (admin)
+// @Summary Delete announcement
+// @Description Permanently delete an announcement. Admin only.
+// @Tags Admin
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path string true "Announcement ID"
+// @Success 200 {object} object{message=string}
+// @Failure 401 {object} handlers.APIResponse "Unauthorized"
+// @Router /api/v1/announcements/{id} [delete]
 func (h *AnnouncementHandler) Delete(c *gin.Context) {
 	idStr := c.Param("id")
 	id, err := uuid.Parse(idStr)
@@ -68,6 +97,13 @@ func (h *AnnouncementHandler) Delete(c *gin.Context) {
 }
 
 // GetActive returns active announcements (public)
+// @Summary Get active announcements
+// @Description Get a list of currently active announcements. Public access.
+// @Tags Admin
+// @Accept json
+// @Produce json
+// @Success 200 {object} object{announcements=array}
+// @Router /api/v1/announcements/active [get]
 func (h *AnnouncementHandler) GetActive(c *gin.Context) {
 	list, err := h.svc.GetActive(c.Request.Context())
 	if err != nil {
diff --git a/veza-backend-api/internal/handlers/feature_flag_handler.go b/veza-backend-api/internal/handlers/feature_flag_handler.go
index 1f02bd831..3a0ca53a8 100644
--- a/veza-backend-api/internal/handlers/feature_flag_handler.go
+++ b/veza-backend-api/internal/handlers/feature_flag_handler.go
@@ -20,6 +20,15 @@ func NewFeatureFlagHandler(svc *services.FeatureFlagService) *FeatureFlagHandler
 }
 
 // List returns all feature flags (admin)
+// @Summary List all feature flags
+// @Description Get a list of all feature flags and their current status. Admin only.
+// @Tags Admin
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} object{feature_flags=array}
+// @Failure 401 {object} handlers.APIResponse "Unauthorized"
+// @Router /api/v1/admin/feature-flags [get]
 func (h *FeatureFlagHandler) List(c *gin.Context) {
 	list, err := h.svc.List(c.Request.Context())
 	if err != nil {
@@ -30,6 +39,17 @@ func (h *FeatureFlagHandler) List(c *gin.Context) {
 }
 
 // Toggle enables or disables a feature flag (admin)
+// @Summary Toggle feature flag
+// @Description Enable or disable a specific feature flag. Admin only.
+// @Tags Admin
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param name path string true "Flag name"
+// @Param data body object{enabled=boolean} true "Toggle data"
+// @Success 200 {object} models.FeatureFlag
+// @Failure 401 {object} handlers.APIResponse "Unauthorized"
+// @Router /api/v1/admin/feature-flags/{name}/toggle [put]
 func (h *FeatureFlagHandler) Toggle(c *gin.Context) {
 	name := c.Param("name")
 	if name == "" {