Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven/llms.txt

Use this file to discover all available pages before exploring further.

Riven has a built-in notification service that fires on two channels: external push notifications sent via Apprise (Discord, Slack, Telegram, Ntfy, and hundreds of other services), and real-time Server-Sent Events (SSE) that the frontend and any custom client can subscribe to for live state change updates. External notifications are triggered when an item reaches the Completed state; SSE events fire on every state transition.

​
Configuration Fields

Notification settings live under the notifications key in Riven’s settings:
FieldTypeDefaultDescription
notifications.enabledboolfalseMaster switch for external (Apprise) notifications
notifications.service_urlslist[string][]One or more Apprise-format URLs
notifications.on_item_typelist[string]["movie","show","season","episode"]Item types that trigger an external notification
Setting enabled to false disables outbound Apprise calls but SSE events continue to fire regardless.

​
Setting Up External Notifications

Discord webhooks are supported natively via Apprise. Riven automatically appends ?format=markdown to any Discord URL so that bold text and links render correctly in the channel.Step 1 — Create a Discord webhook
  1. In your Discord server, go to Server Settings → Integrations → Webhooks.
  2. Click New Webhook, give it a name (e.g. “Riven”), and select the target channel.
  3. Click Copy Webhook URL. It will look like: https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz
Step 2 — Convert to an Apprise URLExtract the two path components from the webhook URL and assemble the Apprise URL:
https://discord.com/api/webhooks/{webhook_id}/{webhook_token}
                                  ↓              ↓
discord://{webhook_id}/{webhook_token}
For example:
discord://1234567890/abcdefghijklmnopqrstuvwxyz
Riven will automatically add ?format=markdown when initializing this URL — you do not need to add it yourself.Step 3 — Apply the configuration
curl -X POST http://localhost:8080/api/v1/settings/set/all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "enabled": true,
      "service_urls": ["discord://1234567890/abcdefghijklmnopqrstuvwxyz"]
    }
  }'

​
Example Configuration

Below is a minimal notifications block you can POST to POST /api/v1/settings/set/all: 
{
  "notifications": {
    "enabled": true,
    "service_urls": [
      "discord://webhook_id/webhook_token"
    ],
    "on_item_type": ["movie", "show"]
  }
}
To read back the current notification settings: 
curl http://localhost:8080/api/v1/settings/get/notifications \
  -H "X-API-Key: YOUR_API_KEY"
To save settings to disk after updating them: 
curl -X POST http://localhost:8080/api/v1/settings/save \
  -H "X-API-Key: YOUR_API_KEY"

​
Real-Time SSE Events

In addition to push notifications, Riven exposes a Server-Sent Events stream for live state changes. Any client — the frontend, a custom dashboard, or a script — can subscribe to an event channel and receive JSON payloads in real time.

​
Available endpoints

EndpointDescription
GET /api/v1/stream/event_typesReturns a list of all active event channel names
GET /api/v1/stream/{event_type}Opens an SSE stream for the given event type

​
Get all event types

curl http://localhost:8080/api/v1/stream/event_types \
  -H "X-API-Key: YOUR_API_KEY"
Example response: 
{
  "event_types": ["item_update", "notifications", "logging"]
}

​
Subscribe to a stream

Connect to any event type with a standard SSE client. The stream stays open and delivers JSON-encoded data as events occur: 
curl -N http://localhost:8080/api/v1/stream/item_update \
  -H "X-API-Key: YOUR_API_KEY"
item_update event payload — fires on every item state change: 
{
  "last_state": "Scraping",
  "new_state": "Downloading",
  "item_id": 42,
  "imdb_id": "tt1234567",
  "tmdb_id": 12345,
  "tvdb_id": null
}
notifications event payload — fires when an item reaches Completed: 
{
  "title": "Inception",
  "type": "movie",
  "year": 2010,
  "duration": 4823,
  "timestamp": "2025-01-15T20:34:12.456789",
  "log_string": "Inception (2010)",
  "imdb_id": "tt1375666"
}
SSE streams fire regardless of whether notifications.enabled is true or false. The enabled flag controls only outbound Apprise calls.

​
How Notifications Are Triggered

When Riven marks an item Completed, the notification service:
  1. Logs a success message with the total duration from request to completion.
  2. Publishes a notifications SSE event so the frontend can show a popup.
  3. If notifications.enabled is true and the item’s type is in on_item_type, sends an Apprise notification to every configured service_url.
The notification body uses Markdown formatting (e.g. **Inception (2010)**) which renders correctly in Discord and other services that support it.

Build docs developers (and LLMs) love

Get started for freeTalk to us