Sending Notifications

Notifications are sent via POST /v1/notifications using a source API key (sk_...).

Basic notification

curl -s https://api.tipoff.dev/v1/notifications \
  -H "Authorization: Bearer sk_your_source_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user_abc",
    "title": "Overdue: Buy groceries",
    "body": "Task was due 2 hours ago",
    "category": "done_snooze_dismiss",
    "priority": "high"
  }'

Full payload

Field	Type	Required	Description
to	string	yes	User ID to send to
title	string	yes	Notification title
body	string	no	Notification body text
priority	string	no	low, normal (default), high, urgent
category	string	no	Action category identifier (must match a registered category)
icon_url	string	no	URL for the notification icon
click_url	string	no	Deep link URL when notification is tapped
metadata	object	no	Opaque JSON, echoed back in action callbacks
collapse_key	string	no	Replaces prior notification with the same key
ttl	integer	no	Seconds until the notification expires

Priority levels

• low — Silent delivery, no sound or badge
• normal — Standard delivery (default)
• high — Time-sensitive, breaks through Focus modes
• urgent — Critical alerts, requires special entitlement

Action categories

Categories define which action buttons appear on the notification. They are registered by sources via POST /v1/categories/sync.

When a user taps an action button, TipOff delivers an action event containing the action identifier and the original metadata from the notification.

Collapse keys

If you send two notifications with the same collapse_key, the second replaces the first on the user’s device. Useful for status updates where only the latest matters.

See also

• REST API Reference for the full endpoint documentation
• Action Delivery for receiving action callbacks