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 stores its entire configuration in a single JSON file inside the data directory (typically data/settings.json). On first launch, the file is generated with sensible defaults and a randomly-generated API key. Every field maps directly to a Pydantic model (AppModel) that is validated on load — if any value is invalid, Riven will refuse to start and log the exact field that failed. You can edit the file directly or use the Settings REST API to read and write individual keys without restarting Riven. Changes made through the API take effect immediately; Riven re-validates and applies updated settings in-process.

​
Top-level settings fields

The following fields live at the root of AppModel and control global behaviour.
FieldTypeDefaultDescription
versionstring(auto)Application version string, updated automatically on upgrade.
api_keystring(auto-generated)Bearer token required for all authenticated API requests. Auto-generated on first run if left empty.
log_levelstring"INFO"Minimum log severity. One of TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL.
enable_network_tracingbooleanfalseLog the full body of every outbound HTTP request and response. Useful for debugging scraper and debrid connectivity.
enable_stream_tracingbooleanfalseLog detailed information for every VFS stream request and response.
retry_intervalinteger86400Seconds between automatic retries for library items that previously failed (set 0 to disable).
tracemallocbooleanfalseEnable Python tracemalloc memory profiling. Intended for development debugging only.
filesystemobject—VFS mount path, cache behaviour, naming templates, and library profiles. See Filesystem.
updatersobject—Plex, Jellyfin, and Emby library-update configuration. See Media Server.
downloadersobject—Debrid service credentials and file-size filters. See Debrid Services.
contentobject—Content source integrations (Overseerr, Trakt, MDBList, etc.). See Content Services.
scrapingobject—Torrent scraper configuration and retry backoff. See Scrapers.
rankingobject—RTN (Rank Torrent Name) quality-ranking preferences.
indexerobject—Schedule offset for newly-aired episode scraping (default 30 min).
databaseobject—PostgreSQL connection string.
notificationsobject—Notification service URLs and item-type triggers.
post_processingobject—Post-processing steps such as subtitle downloading.
loggingobject—File logging rotation, retention, and compression settings.
streamobject—VFS chunk size and stream connection/activity timeouts.

​
Settings API

Riven exposes a REST API for reading and writing configuration at runtime. All settings endpoints are protected by the bearer token in api_key.
MethodPathDescription
GET/api/v1/settings/get/allReturn the complete current settings object.
POST/api/v1/settings/set/allDeep-merge a partial settings object into the current settings, validate, and save.
GET/api/v1/settings/get/{paths}Return one or more dot-separated paths (comma-separated list), e.g. scraping.torrentio,log_level.
POST/api/v1/settings/set/{paths}Set one or more dot-separated paths by supplying a {"path": value} body.
GET/api/v1/settings/schemaReturn the full JSON Schema for AppModel.
GET/api/v1/settings/schema/keysReturn a filtered JSON Schema for the specified top-level keys.
GET/api/v1/settings/loadRe-load settings from disk into memory.
POST/api/v1/settings/savePersist current in-memory settings to disk.

​
Example: update log level via the API

curl -X POST "http://localhost:8080/api/v1/settings/set/all" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"log_level": "DEBUG"}'

​
Example: update a nested field

curl -X POST "http://localhost:8080/api/v1/settings/set/all" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "downloaders": {
      "real_debrid": {
        "enabled": true,
        "api_key": "YOUR_REALDEBRID_KEY"
      }
    }
  }'
Changes written through the API are validated immediately. If a field value is invalid (e.g., a URL that does not start with http:// or https://), the endpoint returns HTTP 400 with a description of the failing field. No partial update is applied.

​
Sub-configuration pages

Debrid Services

Configure Real-Debrid, AllDebrid, or Debrid-Link credentials and file-size filters.

Content Services

Connect Overseerr, Trakt, MDBList, Plex Watchlist, and Listrr as media request sources.

Scrapers

Enable and tune torrent scrapers including Torrentio, Jackett, Prowlarr, and more.

Media Server

Push library refresh notifications to Plex, Jellyfin, or Emby after items are mounted.

Filesystem

Set mount paths, cache parameters, naming templates, and library profiles for the VFS.

Build docs developers (and LLMs) love

Get started for freeTalk to us