git.stella-ops.org/docs/modules/notify/api.md

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.