Notifications

Sellable product

This capability is granted by an API key scoped to the `` product (product face). See the product reference below.

Multi-channel notification capability — operational alerting (Slack/email/webhook fan-out) + end-user in-app notifications + web-push (VAPID). One send-API + one in-app store + a push-subscription registry so products don't each re-roll notification plumbing. Provider/channel secrets resolved server-side (Infisical), never in body/DB/logs. Status: LIVE. v1.1/v1.2 expand-contract (backward-compatible): the web_push channel + the /v1/push/* subscription surface (v1.1) + per-user push history (v1.2, GET /v1/push/history) are ADDITIVE over v1 and DEFAULT-OFF (gated by NOTIFICATIONS_WEB_PUSH_ENABLED) so the v1 surface is unchanged until an operator enables it. Absorbs vagary-platform's local VAPID path (backend/services/push_notification_service.py) — delivery + subscriptions + the history read — so it can be deleted once delivery + subscriptions migrate.

• Group: Comms & workflow
• Contract: contracts/notifications/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/notifications/send

Endpoints

Method	Path	Summary
POST	/v1/notify	Send a notification across one or more channels (Slack/email/webhook)
GET	/v1/notifications	List in-app notifications for the caller's org/user
PUT	/v1/notifications/{id}/read	mark read
DELETE	/v1/notifications/{id}	delete
GET	/v1/push/vapid-public-key	The service VAPID application-server public key (a client needs it to subscribe)
POST	/v1/push/registrations	Register (upsert) a browser web-push subscription for the caller's org
GET	/v1/push/registrations	List the org's push subscriptions (never returns key material)
DELETE	/v1/push/registrations/{sub_id}	Unsubscribe (delete) one push subscription
GET	/v1/push/history	Per-user web_push notification history (the platform get_notification_history read)
GET	/health	liveness
GET	/metrics	Prometheus

Schemas

NotifyRequest

Field	Type	Description
organization_id	string	product-tier tenant (I6)
channels	array
message	string
subject	string
target	object	channel-specific target. slack: {webhook_url?}; webhook: {url, payload?}; email: {email}; in_app: {user_id?}. web_push (v1.1): a routing selector — {user_id} (that user's stored devices), {broadcast:true} (the whole org's devices), or {subscription:{endpoint,keys}} (a direct one-off, no store) — plus optional {site_id, url, data} threaded into the push payload.

NotifyAccepted

Field	Type	Description
notification_id	string
accepted_channels	array

PushSubscription

a W3C Push API PushSubscription (as JSON.stringify(subscription.toJSON()) yields)

Field	Type	Description
endpoint	string
keys	object

PushSubscriptionRegister

Field	Type	Description
subscription	object
user_id	string	optional end-user the subscription belongs to
site_id	string	optional sub-org / brand scope (platform site parity)
platform	string	'web' (VAPID); 'fcm'/'apns' reserved

PushHistoryItem

one per-user web_push history record (display metadata only — no key material). Recorded once per targeted user per web_push send. delivered_count is the real device count for a per-user send and 0 for a broadcast row (a broadcast's aggregate is not attributable per user — it lives in the delivery log).

Field	Type	Description
notification_id	string	the /v1/notify id this history row belongs to
user_id	string
title	string	push title (= notify subject)
body	string	push body (= notify message)
url	string
data	object	opaque payload data (from target.data)
site_id	string
status	string	terminal send outcome
delivered_count	integer
created_at	number	epoch seconds

Error

Field	Type	Description
error	string

---

Generated by scripts/gen-capability-docs.py from contracts/notifications/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.