Notification Endpoint Catalog

Summary

This is the single authoritative catalog. Every verified Notification endpoint appears exactly once: 17 native operations on notification-service, 10 compatibility operations on the monolith, and 2 gateway aggregation operations that read notification data. Gateway proxy routes carry no handlers of their own and are documented in gateway and compatibility.

Audience

API consumers, engineers, architects, QA, support, security reviewers and implementation partners.

Reference Content

The verified reference material for this topic is set out in the sections below.

Reading this catalog

• Authentication and Authorization record what the reviewed source declares on the endpoint itself, not what an upstream component might add.
• Tenant behavior records how the handler treats tenant identity.
• Validation records the guard clauses present in the handler.
• Compatibility classification is one of Native, Compatibility or Gateway aggregation.
• No example identifiers, hosts, credentials or payload captures appear in this catalog.

Native operational endpoints

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/	Service information	None declared	None declared	Not applicable	None	ApiResponse<ServiceInfoResponse> with correlation id	Native	microservices/src/shared-kernel/Extensions/EndpointRouteBuilderExtensions.cs
GET	/health	Health-check report	None declared	None declared	Not applicable	None	Default health-check report	Native	microservices/src/notification-service/Program.cs

Native inbox endpoints

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/notifications/my	Recipient in-app inbox	None declared	None declared	tenantId query value matched directly against Recipients.TenantId; null matches null-tenant rows	recipientRef required; take clamped 1–500	200 anonymous projection array; empty array when no recipient matches	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
POST	/notifications/{id:guid}/read	Mark an in-app message read	None declared	None declared	Not scoped — lookup is by message id alone	Route guid constraint only	200 anonymous projection; 404 when absent	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs

Native template endpoints

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/notification-templates	List templates with optional filters	None declared	None declared	Optional tenantId filter; unfiltered by default	Channel filter normalized; no other checks	200 template entity array	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
POST	/notification-templates	Create the next version for a tenant, key and channel	None declared	None declared	tenantId from body; blank becomes null (global)	templateKey and channel required; channel must be known	201 with Location and the created entity; 400 on failure	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
PUT	/notification-templates/{id:guid}	Update a template row in place	None declared	None declared	Not scoped — lookup is by template id alone	Route guid constraint; only non-null fields applied	200 updated entity; 404 when absent	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
POST	/notification-templates/{id:guid}/test	Render, and optionally send, a template	None declared	None declared	Inherits the template's tenant	Route guid constraint; send requires toAddress	200 render result, or render plus delivery outcome; 404 when absent	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs

Native administration endpoints

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/notifications/{id:guid}	Read one message	None declared	None declared	Not scoped	Route guid constraint	200 message entity; 404 when absent	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
GET	/notifications/{id:guid}/attempts	Delivery attempts for a message	None declared	None declared	Not scoped	Route guid constraint	200 attempt array, ordered by attempt number	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
POST	/notifications/{id:guid}/retry	Re-drive delivery of a message	None declared	None declared	Not scoped	Route guid constraint	200 status projection; 404 when absent	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
GET	/notifications/failed	Messages that exhausted retries	None declared	None declared	Not scoped — all tenants	take clamped 1–500	200 message array	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
GET	/notifications/processed/{eventId:guid}	Idempotency lookup for a consumed event	None declared	None declared	Not scoped	Route guid constraint	200 processed-event row; 404 when absent	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
GET	/notifications/audit	Audit-trail query	None declared	None declared	Not scoped — all tenants	take clamped 1–1000	200 audit array	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
GET	/notifications/stats	Aggregate counts	None declared	None declared	Not scoped — platform-wide counts	None	200 anonymous count projection	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs

Native test endpoints

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
POST	/notifications/test/dispatch	Run an event through the dispatcher without the broker	None declared	None declared	tenantId taken from the body	eventType required	200 outcome projection	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs
POST	/notifications/test/publish	Publish an event onto the bus	None declared	None declared	tenantId written to message metadata	eventType required	200 publish acknowledgement; 502 when the bus reports failure	Native	microservices/src/notification-service/Api/NotificationEndpoints.cs

Compatibility endpoints — monolith notifications

All six declare [Authorize] at the controller and resolve the caller by email claim.

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/api/notifications	Unread notifications for the caller	Required	Authenticated caller only	Implicit via the resolved user record	None	200 DTO array, capped at 20; 401 when unresolved	Compatibility	Controllers/NotificationsController.cs
GET	/api/notifications/all	All notifications for the caller	Required	Authenticated caller only	Implicit via the resolved user record	None	200 DTO array, capped at 200; 401 when unresolved	Compatibility	Controllers/NotificationsController.cs
GET	/api/notifications/unread-count	Unread count	Required	Authenticated caller only	Implicit via the resolved user record	None	200 count projection; 401 when unresolved	Compatibility	Controllers/NotificationsController.cs
POST	/api/notifications/{id}/read	Mark one notification read	Required	Ownership enforced — the row must belong to the caller	Implicit via the resolved user record	Optional source selects the legacy table	200 DTO; 404 when not owned or absent	Compatibility	Controllers/NotificationsController.cs
POST	/api/notifications/{id}/dismiss	Alias that delegates to the read action	Required	Ownership enforced	Implicit via the resolved user record	None	Same as the read action	Compatibility	Controllers/NotificationsController.cs
POST	/api/notifications/read-all	Mark all caller notifications read	Required	Scoped to the caller's rows	Implicit via the resolved user record	None	200 updated-count projection	Compatibility	Controllers/NotificationsController.cs

Compatibility endpoints — monolith templates

All four declare [Authorize] at the controller.

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/api/notification-templates	List templates by event key	Required	Authenticated caller only	Tenant-scoped override flag on each row	None	200 template DTO array	Compatibility	Controllers/NotificationTemplatesController.cs
PUT	/api/notification-templates/{eventKey}	Save a template for an event key	Required	Authenticated caller only	Tenant-scoped override	Bound update DTO	200 saved DTO	Compatibility	Controllers/NotificationTemplatesController.cs
POST	/api/notification-templates/{eventKey}/preview	Render a preview with sample data	Required	Authenticated caller only	Tenant-scoped override	Bound preview request	200 preview DTO	Compatibility	Controllers/NotificationTemplatesController.cs
POST	/api/notification-templates/{eventKey}/reset	Reset a template to its definition default	Required	Authenticated caller only	Tenant-scoped override	None	200 reset DTO	Compatibility	Controllers/NotificationTemplatesController.cs

Gateway aggregation endpoints

These are gateway-owned handlers that read notification data as one input among several. They are not part of the notification service contract.

Method	Route	Purpose	Auth	Authz	Tenant	Validation	Response	Class	Source
GET	/ess/notifications	Employee self-service notification list	Gateway-owned	Gateway-owned	Recipient reference derived from the request	Fixed page size	Aggregated single-source result	Gateway aggregation	microservices/src/gateway-api/EssEndpoints.cs
GET	/ess/dashboard	Self-service dashboard including a notification slice	Gateway-owned	Gateway-owned	Recipient reference derived from the request	Fixed page size	Aggregated multi-source result	Gateway aggregation	microservices/src/gateway-api/EssEndpoints.cs

Totals

Surface	Operations
Native operational	2
Native inbox	2
Native template	4
Native administration	7
Native test	2
Native total	17
Compatibility — notifications	6
Compatibility — templates	4
Compatibility total	10
Gateway aggregation	2
Catalog total	29

Verified absence

No native endpoint exists for deleting a template, deleting a message, managing recipient preferences, exporting notification history, resending in bulk, or querying delivery by channel. No PATCH or DELETE verb is mapped anywhere on the native surface.

Classification

Implemented catalog; the compatibility rows are Transitional.

Requires confirmation

Which endpoints are approved for direct external consumption, and whether the unscoped administration endpoints are intended to remain platform-wide, require confirmation.

Related Articles

• Notification API documentation
• Notification API overview
• DTO catalog

See Also

• Gateway and compatibility
• API limitations

Keywords

• Notification API
• Endpoint Catalog
• Draft API documentation

Source References

• microservices/src/notification-service/Api/NotificationEndpoints.cs
• microservices/src/notification-service/Program.cs
• microservices/src/shared-kernel/Extensions/EndpointRouteBuilderExtensions.cs
• Controllers/NotificationsController.cs
• Controllers/NotificationTemplatesController.cs
• microservices/src/gateway-api/EssEndpoints.cs

Revision Information

• Status: Draft
• Last reviewed: 2026-07-21
• Review cycle: Quarterly