{"openapi":"3.0.0","info":{"title":"Centrali Notification Service API","version":"5.1.2","description":"API documentation for the Centrali Notification Service - Email notifications, WebSocket real-time updates, and notification management.","contact":{"name":"Centrali Support"}},"servers":[{"url":"https://api.centrali.io/notification/workspace/{workspaceSlug}/api/v1","description":"Workspace-scoped API","variables":{"workspaceSlug":{"default":"demo","description":"The workspace slug"}}}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the IAM service"}},"schemas":{"Error":{"type":"object","required":["error","message","status","timestamp","path"],"properties":{"error":{"type":"string","example":"NOTIFICATION_ERROR","description":"Machine-readable error code"},"message":{"type":"string","example":"Failed to send notification","description":"Human-readable error message"},"status":{"type":"integer","example":400,"description":"HTTP status code"},"timestamp":{"type":"string","format":"date-time","example":"2026-03-02T10:00:00.000Z"},"path":{"type":"string","example":"/workspace/my-ws/api/v1/notifications","description":"Request path"},"requestId":{"type":"string","description":"Optional request ID for tracing"}}},"Notification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["email","websocket","push"]},"recipient":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"status":{"type":"string","enum":["pending","sent","failed","delivered"]},"workspace_slug":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"}}},"EmailTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"subject":{"type":"string"},"html_body":{"type":"string"},"text_body":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"workspace_slug":{"type":"string"}}},"WebSocketEvent":{"type":"object","properties":{"event":{"type":"string"},"channel":{"type":"string"},"data":{"type":"object"},"timestamp":{"type":"string","format":"date-time"}}}}},"security":[{"bearerAuth":[]}],"paths":{"/notifications":{"post":{"summary":"Create a notification","tags":["Notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","type","title"],"properties":{"userId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["email","in_app","push"]},"title":{"type":"string"},"body":{"type":"string"},"data":{"type":"object","description":"Additional notification data"}}}}}},"responses":{"201":{"description":"Notification created successfully"}}}},"/notifications/{userId}":{"get":{"summary":"Get user notifications","tags":["Notifications"],"parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of notifications","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}}}}}}}}}},"/notifications/{userId}/unread":{"get":{"summary":"Get unread notifications","tags":["Notifications"],"parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of unread notifications"}}}},"/notifications/{userId}/unread-count":{"get":{"summary":"Get unread notification count","tags":["Notifications"],"parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Unread count","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"}}}}}}}}},"/notifications/{id}/read":{"delete":{"summary":"Mark a notification as read (deletes it)","tags":["Notifications"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Notification ID to mark as read"}],"responses":{"200":{"description":"Notification marked as read"}}}},"/notifications/{userId}/clear":{"delete":{"summary":"Clear all notifications","tags":["Notifications"],"parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"All notifications cleared"}}}},"/service/version":{"get":{"summary":"Get service version","description":"Retrieve the current version information of the Notification service","tags":["Service"],"responses":{"200":{"description":"Service version information","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"name":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/service/health":{"get":{"summary":"Get service health","description":"Check the health status of the Notification service and its database dependency","tags":["Service"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"timestamp":{"type":"string","format":"date-time"},"dependencies":{"type":"object","properties":{"database":{"type":"string"}}},"pool":{"type":"object","properties":{"active":{"type":"integer"},"idle":{"type":"integer"},"waiting":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"503":{"description":"Service is unhealthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"dependencies":{"type":"object"}}}}}}}}},"/subscriptions/events":{"get":{"summary":"Get available notification events","tags":["Notification Preferences"],"description":"Returns all event types that users can subscribe to","responses":{"200":{"description":"List of notification event types","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"}}}}}}}}}}}},"/subscriptions/withFilters":{"get":{"summary":"Get preferences by event and filter","tags":["Notification Preferences"],"parameters":[{"in":"query","name":"event","schema":{"type":"string"},"description":"Event type to filter by"},{"in":"query","name":"filter","schema":{"type":"string"},"description":"Additional filter criteria"}],"responses":{"200":{"description":"Filtered preferences"}}}},"/subscriptions/me":{"get":{"summary":"Get current user's notification preferences","tags":["Notification Preferences"],"responses":{"200":{"description":"User's notification preferences","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string"},"method":{"type":"string","enum":["email","in_app"]},"enabled":{"type":"boolean"}}}}}}}}}}}},"/subscriptions":{"post":{"summary":"Create a notification preference","tags":["Notification Preferences"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","method"],"properties":{"event":{"type":"string","description":"Event type to subscribe to"},"method":{"type":"string","enum":["email","in_app"]},"enabled":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Preference created"}}}},"/subscriptions/enable-both":{"post":{"summary":"Enable both email and in-app for an event","tags":["Notification Preferences"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"type":"string","description":"Event type to enable both methods for"}}}}}},"responses":{"200":{"description":"Both methods enabled"}}}},"/subscriptions/{id}/toggle":{"patch":{"summary":"Toggle a notification preference","tags":["Notification Preferences"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Preference toggled"}}}},"/subscriptions/{id}":{"delete":{"summary":"Delete a notification preference","tags":["Notification Preferences"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Preference deleted"}}}}},"tags":[{"name":"Notifications","description":"User notification management"},{"name":"Notification Preferences","description":"Manage notification preferences and subscriptions"}]}