# 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 `notifications/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 `notifications/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.