7943cfb3af
Bundled pre-session doc + ops work: - docs/modules/**: sync across advisory-ai, airgap, cli, excititor, export-center, findings-ledger, notifier, notify, platform, router, sbom-service, ui, web (architectural + operational updates) - docs/features/**: updates to checked excititor vex pipeline, developer workspace, quick verify drawer - docs top-level: README, quickstart, API_CLI_REFERENCE, UI_GUIDE, code-of-conduct/TESTING_PRACTICES updates - docs/qa/feature-checks/: FLOW.md + excititor state update - docs/implplan/: remaining sprint updates + new Concelier source credentials sprint (SPRINT_20260422_003) - docs-archived/implplan/: 30 sprint archival moves (ElkSharp series, misc completed sprints) - devops/compose: .env + services compose + env example + router gateway config updates File-level granularity preserved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
44 lines
2.6 KiB
Markdown
44 lines
2.6 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 `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.
|
|
- Digest schedule cadence is worker configuration (`Notifier:DigestSchedule`), not an API-managed resource; current digest endpoints administer rendered output or open windows only.
|
|
|
|
## 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.
|