Notifications

Manage your in-app notification feed and configure delivery preferences per event category.

List Notifications

GET /v1/notifications

Returns a paginated list of notifications for the authenticated tenant, ordered by most recent first.

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	50	Max records to return
offset	integer	No	0	Records to skip
unread_only	boolean	No	false	When true, returns only unread notifications

Example Request

curl "https://api.rymi.live/v1/notifications?limit=20&unread_only=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "notif_abc123",
      "tenant_id": "550e8400-...",
      "event_category": "billing.low_balance",
      "title": "Low Balance Warning",
      "message": "Your account balance is below $5.00. Top up to avoid call interruptions.",
      "is_read": false,
      "metadata": {
        "balance_usd": 4.20
      },
      "created_at": "2026-04-01T14:30:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

Errors

Status	Meaning
401	Missing or invalid API key

---

Mark All as Read

PUT /v1/notifications/read-all

Marks all unread notifications as read for the authenticated tenant. No request body required.

Example Request

curl -X PUT https://api.rymi.live/v1/notifications/read-all \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true
}

Errors

Status	Meaning
401	Missing or invalid API key

---

Mark Notification as Read

PUT /v1/notifications/:id/read

Marks a single notification as read.

Path Parameters

Parameter	Type	Description
id	string	Notification ID

Example Request

curl -X PUT https://api.rymi.live/v1/notifications/notif_abc123/read \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true
}

Errors

Status	Meaning
401	Missing or invalid API key
404	Notification not found for this tenant

---

Get Notification Preferences

GET /v1/notifications/preferences

Returns delivery preferences for each event category. Preferences control which channels (email, SMS, in-app, webhook) receive notifications.

Example Request

curl https://api.rymi.live/v1/notifications/preferences \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "event_category": "billing.low_balance",
      "email_enabled": true,
      "sms_enabled": false,
      "in_app_enabled": true,
      "webhook_enabled": false
    },
    {
      "event_category": "call.failed",
      "email_enabled": true,
      "sms_enabled": false,
      "in_app_enabled": true,
      "webhook_enabled": true
    }
  ]
}

Errors

Status	Meaning
401	Missing or invalid API key

---

Update Notification Preference

PUT /v1/notifications/preferences

Update delivery channels for a specific event category. Creates the preference if it doesn't exist.

Request Body

Field	Type	Required	Default	Description
event_category	string	Yes	—	Event category to configure (e.g., billing.low_balance, call.failed)
email_enabled	boolean	No	Unchanged	Enable or disable email delivery
sms_enabled	boolean	No	Unchanged	Enable or disable SMS delivery
in_app_enabled	boolean	No	Unchanged	Enable or disable in-app notification
webhook_enabled	boolean	No	Unchanged	Enable or disable webhook delivery

Example Request

curl -X PUT https://api.rymi.live/v1/notifications/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_category": "billing.low_balance",
    "email_enabled": true,
    "sms_enabled": true,
    "in_app_enabled": true,
    "webhook_enabled": false
  }'

Response 200

{
  "data": {
    "event_category": "billing.low_balance",
    "email_enabled": true,
    "sms_enabled": true,
    "in_app_enabled": true,
    "webhook_enabled": false
  }
}

Errors

Status	Meaning
400	Missing event_category
401	Missing or invalid API key

---

Send Test Notification

POST /v1/notifications/test

Triggers a test notification to verify your notification delivery pipeline. Useful for testing preference channels. No request body required.

Example Request

curl -X POST https://api.rymi.live/v1/notifications/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "jobId": "job_notif_123"
}

Errors

Status	Meaning
401	Missing or invalid API key
500	Notification service not configured