docs consolidation work

docs/modules/notify/api.md

@@ -0,0 +1,42 @@
+# Notifications API
+
+> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
+
+Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001)
+
+All endpoints require `Authorization: Bearer <token>` and `X-Stella-Tenant` header. Responses use the common error envelope (`docs/api/overview.md`). Paths are rooted at `/api/v1/notify`.
+
+## Channels
+- `POST /channels` — create channel. Body matches `channels.md` schema. Returns `201` + channel.
+- `GET /channels` — list channels (deterministic order: type ASC, id ASC). Supports `type` filter.
+- `GET /channels/{id}` — fetch single channel.
+- `DELETE /channels/{id}` — soft-delete; fails if referenced by active rules unless `force=true` query.
+
+## Rules
+- `POST /rules` — create/update rule; idempotency via `Idempotency-Key`.
+- `GET /rules` — list rules with paging (`page_token`, `page_size`). Sorted by `name` ASC.
+- `POST /rules:preview` — dry-run rule against sample event; returns matched actions and rendered templates.
+
+## Policies & escalations
+- `POST /policies/escalations` — create escalation policy (see `escalations.md`).
+- `GET /policies/escalations` — list policies.
+
+## Deliveries & digests
+- `GET /deliveries` — query delivery ledger; filters: `status`, `channel`, `rule_id`, `from`, `to`. Sorted by `createdUtc` DESC then `id` ASC.
+- `GET /deliveries/{id}` — single delivery with rendered payload hash and attempts.
+- `POST /digests/preview` — preview digest rendering for a tenant/rule set; returns deterministic body/hash without sending.
+
+## Acknowledgements
+- `POST /acks/{token}` — acknowledge an escalation token. Validates DSSE signature, token expiry, and tenant. Returns `200` with cancellation summary.
+
+## Simulations
+- `POST /simulations/rules` — simulate a rule set for a supplied event payload; no side effects. Returns matched actions and throttling outcome.
+
+## Health & metadata
+- `GET /health` — liveness/readiness probes.
+- `GET /metadata` — returns supported channel types, max payload sizes, and server version.
+
+## Determinism notes
+- All list endpoints are stable and include `next_page_token` when applicable.
+- Templates render with fixed locale `en-US` unless `Accept-Language` provided; rendering is pure (no network calls).
+- `bodyHash` uses SHA-256 over canonical JSON; repeated sends with identical inputs produce identical hashes and are de-duplicated.