9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# 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.
|