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.

Content services are the intake layer for Riven — they watch external sources and push new movie or show requests into the pipeline for scraping and downloading. Multiple services can run simultaneously; Riven deduplicates items so the same title is never processed twice regardless of how many sources request it. All content services live under the content key in AppModel. Each service has its own enabled flag and update_interval (in seconds) that controls how often Riven polls for new items.
Overseerr is a request management tool for Plex libraries. Riven can poll Overseerr for approved requests or receive them instantly via webhook.
​
content.overseerr.enabled
boolean
default:"false"
Enable the Overseerr integration.
​
content.overseerr.url
string
default:"\"http://localhost:5055\""
URL of your Overseerr instance, including protocol and port.
​
content.overseerr.api_key
string
default:"\"\""
Overseerr API key. Generate one in Overseerr under Settings → General → API Key. The key must be exactly 68 characters.
​
content.overseerr.update_interval
integer
default:"60"
Seconds between polls for new approved requests. Minimum 5 seconds.
​
content.overseerr.use_webhook
boolean
default:"false"
When true, Riven performs a single initial poll to catch up on any existing approved requests, then switches to webhook-only mode. New requests are delivered instantly without polling.
Webhook setupIf use_webhook is enabled, configure Overseerr to send notifications to:
POST http://<riven-host>:8080/api/v1/webhook/overseerr
In Overseerr, go to Settings → Notifications → Webhook and set the URL above. Select the Request Approved event type.Example configuration
{
  "content": {
    "overseerr": {
      "enabled": true,
      "url": "http://localhost:5055",
      "api_key": "YOUR_OVERSEERR_API_KEY",
      "update_interval": 60,
      "use_webhook": false
    }
  }
}
The Plex Watchlist integration monitors one or more RSS feeds generated by Plex and adds any watchlisted titles to Riven automatically.
​
content.plex_watchlist.enabled
boolean
default:"false"
Enable the Plex Watchlist integration.
​
content.plex_watchlist.rss
list[string]
default:"[]"
One or more Plex Watchlist RSS feed URLs. Generate your feed URL from https://rss.plex.tv after signing in with your Plex account. You can add feeds from multiple Plex accounts.
​
content.plex_watchlist.update_interval
integer
default:"60"
Seconds between RSS feed polls. Minimum 5 seconds.
Example configuration
{
  "content": {
    "plex_watchlist": {
      "enabled": true,
      "rss": [
        "https://rss.plex.tv/YOUR_WATCHLIST_RSS_TOKEN"
      ],
      "update_interval": 60
    }
  }
}
MDBList hosts community-curated media lists. Riven monitors one or more list IDs and adds all their contents to the queue.
​
content.mdblist.enabled
boolean
default:"false"
Enable the MDBList integration.
​
content.mdblist.api_key
string
default:"\"\""
MDBList API key. Find it in your MDBList profile settings.
​
content.mdblist.lists
list[integer | string]
default:"[]"
List of MDBList list IDs to monitor. IDs can be integers or strings. Find the ID in the MDBList URL for your chosen list.
​
content.mdblist.update_interval
integer
default:"86400"
Seconds between list polls. Defaults to 24 hours (86400). Minimum 5 seconds.
Example configuration
{
  "content": {
    "mdblist": {
      "enabled": true,
      "api_key": "YOUR_MDBLIST_API_KEY",
      "lists": [12345, 67890],
      "update_interval": 86400
    }
  }
}
Listrr provides automated, regularly-updated movie and TV show lists. Separate list IDs are configured for movies and shows.
​
content.listrr.enabled
boolean
default:"false"
Enable the Listrr integration.
​
content.listrr.api_key
string
default:"\"\""
Listrr API key. Generate one in your Listrr account settings.
​
content.listrr.movie_lists
list[string]
default:"[]"
Listrr movie list IDs to monitor.
​
content.listrr.show_lists
list[string]
default:"[]"
Listrr TV show list IDs to monitor.
​
content.listrr.update_interval
integer
default:"86400"
Seconds between list polls. Defaults to 24 hours (86400). Minimum 5 seconds.
Example configuration
{
  "content": {
    "listrr": {
      "enabled": true,
      "api_key": "YOUR_LISTRR_API_KEY",
      "movie_lists": ["abc123"],
      "show_lists": ["def456"],
      "update_interval": 86400
    }
  }
}
Trakt is a media tracking service with rich API support. Riven can monitor personal watchlists, collections, custom user lists, and site-wide trending or popular content.
​
content.trakt.enabled
boolean
default:"false"
Enable the Trakt integration.
​
content.trakt.api_key
string
default:"\"\""
Trakt API key (Client ID). Create an application at https://trakt.tv/oauth/applications/new to obtain one.
​
content.trakt.watchlist
list[string]
default:"[]"
Trakt usernames whose watchlists Riven should monitor. Items are pulled on every update interval.
​
content.trakt.user_lists
list[string]
default:"[]"
Full URLs of Trakt user lists to monitor, e.g. https://trakt.tv/users/someuser/lists/my-list.
​
content.trakt.collection
list[string]
default:"[]"
Trakt usernames whose collections Riven should monitor.
​
content.trakt.fetch_trending
boolean
default:"false"
Automatically add the current Trakt trending movies and shows. Trending data is refreshed at most once per day regardless of update_interval.
​
content.trakt.trending_count
integer
default:"10"
Number of trending movies and shows to fetch when fetch_trending is enabled. Minimum 1.
​
content.trakt.fetch_popular
boolean
default:"false"
Automatically add the current Trakt popular movies and shows.
​
content.trakt.popular_count
integer
default:"10"
Number of popular movies and shows to fetch when fetch_popular is enabled. Minimum 1.
​
content.trakt.fetch_most_watched
boolean
default:"false"
Automatically add the most-watched movies and shows for the configured period.
​
content.trakt.most_watched_period
string
default:"\"weekly\""
Period for most-watched results. One of daily, weekly, monthly, or yearly.
​
content.trakt.most_watched_count
integer
default:"10"
Number of most-watched items to fetch. Minimum 1.
​
content.trakt.update_interval
integer
default:"86400"
Seconds between watchlist, collection, and user-list polls. Defaults to 24 hours. Minimum 5 seconds.
​
content.trakt.proxy_url
string
default:"\"\""
Optional proxy URL for Trakt API requests.
OAuth configurationTrakt OAuth is required for accessing private watchlists and collections. Provide your OAuth app credentials in the oauth sub-object, then initiate the flow:
​
content.trakt.oauth.oauth_client_id
string
default:"\"\""
OAuth application Client ID from your Trakt application settings.
​
content.trakt.oauth.oauth_client_secret
string
default:"\"\""
OAuth application Client Secret.
​
content.trakt.oauth.oauth_redirect_uri
string
default:"\"\""
Redirect URI registered with your Trakt application.
To authorize, call the initiate endpoint and follow the redirect:
curl "http://localhost:8080/api/v1/trakt/oauth/initiate" \
  -H "Authorization: Bearer YOUR_RIVEN_API_KEY"
Complete the Trakt authorization page, then Riven stores the access and refresh tokens automatically in content.trakt.oauth.access_token and content.trakt.oauth.refresh_token.Example configuration
{
  "content": {
    "trakt": {
      "enabled": true,
      "api_key": "YOUR_TRAKT_CLIENT_ID",
      "watchlist": ["myusername"],
      "user_lists": [],
      "collection": [],
      "fetch_trending": false,
      "trending_count": 10,
      "fetch_popular": false,
      "popular_count": 10,
      "fetch_most_watched": false,
      "most_watched_period": "weekly",
      "most_watched_count": 10,
      "update_interval": 86400,
      "oauth": {
        "oauth_client_id": "",
        "oauth_client_secret": "",
        "oauth_redirect_uri": "",
        "access_token": "",
        "refresh_token": ""
      }
    }
  }
}
Trending and popular data is only refreshed once every 24 hours internally, even if update_interval is shorter. This reduces unnecessary API calls to Trakt.

Build docs developers (and LLMs) love

Get started for freeTalk to us