System API: Health, Stats, Logs, Debug, and Webhooks

The System API covers the operational surface of Riven: health probes, aggregated library statistics, log access, debug bundle generation, VFS and mount introspection, downloader account information, API key rotation, and Trakt OAuth. Most routes sit directly under /api/v1 (no sub-prefix). All endpoints except GET /api/v1/ require a valid API key.

Root

GET /

Returns a basic liveness confirmation. This is the only endpoint that does not require authentication, making it suitable for container health checks.

curl http://localhost:8080/api/v1/

message

string

Always "Riven is running!".

version

string

Current Riven version string (e.g. "0.18.0").

Example response

{
  "message": "Riven is running!",
  "version": "0.18.0"
}

Health

GET /health

Returns the initialization state of the main Program service. Use this probe after the root check to confirm that Riven has finished booting.

curl http://localhost:8080/api/v1/health \
  -H "x-api-key: YOUR_KEY"

message

string

"True" when Program.initialized is True; "False" otherwise.

Example response

{
  "message": "True"
}

Services

GET /services

Returns an object mapping every registered service key to a boolean indicating whether that service is currently initialized and running.

curl http://localhost:8080/api/v1/services \
  -H "x-api-key: YOUR_KEY"

Example response

{
  "real_debrid": true,
  "torrentio": true,
  "jackett": false,
  "trakt": true,
  "overseerr": true,
  "plex": true
}

Statistics

GET /stats

Returns aggregated counts and activity data for the media library.

curl http://localhost:8080/api/v1/stats \
  -H "x-api-key: YOUR_KEY"

total_items

integer

Total number of MediaItem rows.

total_movies

integer

Number of movie items.

total_shows

integer

Number of TV show items.

total_seasons

integer

Number of season items.

total_episodes

integer

Number of episode items.

total_symlinks

integer

Number of movies and episodes that have an associated FilesystemEntry (i.e. are symlinked).

incomplete_items

integer

Number of items whose last_state is not Completed.

states

object

Dictionary mapping each States enum value to its item count. Example: {"Completed": 1234, "Failed": 5}.

activity

object

Dictionary mapping ISO 8601 date strings to the number of items requested on that date. Example: {"2024-11-15": 12}.

media_year_releases

object[]

Array of {"year": 2023, "count": 45} objects showing how many items were released in each year.

Example response

{
  "total_items": 5432,
  "total_movies": 1200,
  "total_shows": 180,
  "total_seasons": 900,
  "total_episodes": 3152,
  "total_symlinks": 4200,
  "incomplete_items": 32,
  "states": {
    "Completed": 5400,
    "Failed": 12,
    "Requested": 20
  },
  "activity": {
    "2024-11-14": 8,
    "2024-11-15": 14
  },
  "media_year_releases": [
    {"year": 2022, "count": 340},
    {"year": 2023, "count": 521}
  ]
}

Events

GET /events

Return a snapshot of pending event updates from the Event Manager. The response maps each event type name to a list of item IDs that have a queued event of that type. Useful for debugging pipeline queues without connecting to the SSE stream.

curl http://localhost:8080/api/v1/events \
  -H "x-api-key: YOUR_KEY"

events

object

Dictionary mapping event type strings to arrays of integer item IDs. Example: {"Scraping": [42, 99], "Downloading": [17]}.

Example response

{
  "events": {
    "Scraping": [42, 99],
    "Downloading": [17]
  }
}

Logs

GET /logs

Read the current log file and return every line as a string array. This is a point-in-time snapshot — use the SSE logging stream at /api/v1/stream/logging for a live tail.

curl http://localhost:8080/api/v1/logs \
  -H "x-api-key: YOUR_KEY"

logs

string[]

Array of log lines in the order they appear in the log file.

Returns 404 if no log-file handler is configured.

POST /upload_logs

Upload the current log file to paste.c-net.org and return a public URL. The service has a 50 MB file-size limit and a 180-day retention period.

curl -X POST http://localhost:8080/api/v1/upload_logs \
  -H "x-api-key: YOUR_KEY"

success

boolean

Whether the upload succeeded.

url

string

Public URL of the uploaded log file.

Example response

{
  "success": true,
  "url": "https://paste.c-net.org/AbCdEfGh"
}

Debug bundle

POST /debug

Generate a comprehensive debug bundle in one call. This endpoint:

Uploads the current log file to paste.c-net.org.
Creates a local database backup snapshot.
Collects system information.

curl -X POST http://localhost:8080/api/v1/debug \
  -H "x-api-key: YOUR_KEY"

success

boolean

true only if both the log upload and the database backup succeeded.

log_url

string|null

Public URL of the uploaded log file, or null if the upload failed.

db_backup_filename

string|null

Filename of the database backup on the server, or null if the backup failed.

system_info

object

Show system_info fields

platform

string

OS platform string from platform.platform().

python_version

string

Python version string.

cpu_count

integer

Number of logical CPU cores.

load_avg

number[]

1, 5, and 15-minute load averages.

memory

string

Total RAM in human-readable form (e.g. "15.61GB").

swap

string

Total swap in human-readable form.

disk

string

Total disk size in human-readable form.

errors

string[]

List of error messages for any steps that failed. Empty on full success.

Example response

{
  "success": true,
  "log_url": "https://paste.c-net.org/XyZaBcDe",
  "db_backup_filename": "riven_backup_2024-11-15T12-34-56.db",
  "system_info": {
    "platform": "Linux-6.6.0-x86_64",
    "python_version": "3.12.0",
    "cpu_count": 8,
    "load_avg": [0.52, 0.61, 0.48],
    "memory": "15.61GB",
    "swap": "2.00GB",
    "disk": "931.51GB"
  },
  "errors": []
}

Calendar

GET /calendar

Fetch a calendar view of all media items in the library grouped by release date.

curl http://localhost:8080/api/v1/calendar \
  -H "x-api-key: YOUR_KEY"

data

object

Dictionary mapping integer date keys to objects describing items releasing on that date.

Mount

GET /mount

List all files currently present in the Riven VFS mount directory. The response maps each filename to its absolute filesystem path.

curl http://localhost:8080/api/v1/mount \
  -H "x-api-key: YOUR_KEY"

files

object

Dictionary of filename → filepath entries. Example: {"movie.mkv": "/mnt/riven/movies/movie.mkv"}.

VFS statistics

GET /vfs_stats

Return internal statistics from the Riven VFS file-system layer.

curl http://localhost:8080/api/v1/vfs_stats \
  -H "x-api-key: YOUR_KEY"

stats

object

Nested dictionary of VFS opener statistics keyed by stat name.

Downloader account info

GET /downloader_user_info

Return account information from all initialized debrid downloader services (Real-Debrid, AllDebrid, Debrid-Link).

curl http://localhost:8080/api/v1/downloader_user_info \
  -H "x-api-key: YOUR_KEY"

services

object[]

Array of service account info objects.

Show DownloaderUserInfo fields

service

string

Service identifier: realdebrid, alldebrid, or debridlink.

username

string|null

Account username if available.

string|null

Account email address if available.

user_id

integer|string

Unique account ID on the service.

premium_status

string

"premium" or "free".

premium_expires_at

string|null

ISO 8601 datetime of premium expiry.

premium_days_left

integer|null

Days remaining on premium subscription.

points

integer|null

Loyalty/fidelity points balance where applicable.

total_downloaded_bytes

integer|null

Lifetime downloaded bytes.

cooldown_until

string|null

ISO 8601 datetime until which the account is on cooldown, or null.

Example response

{
  "services": [
    {
      "service": "realdebrid",
      "username": "jsmith",
      "email": "jsmith@example.com",
      "user_id": 123456,
      "premium_status": "premium",
      "premium_expires_at": "2025-06-01T00:00:00",
      "premium_days_left": 198,
      "points": 800,
      "total_downloaded_bytes": 107374182400,
      "cooldown_until": null
    }
  ]
}

Returns 503 if no downloader service is initialized, 500 if no account info could be retrieved from any service.

API key generation

POST /generateapikey

Generate a new random API key, persist it immediately to the settings file, and return it. The previous key is invalidated as soon as this response is received.

curl -X POST http://localhost:8080/api/v1/generateapikey \
  -H "x-api-key: YOUR_CURRENT_KEY"

message

string

The newly generated API key string.

Example response

{
  "message": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Trakt OAuth

GET /trakt/oauth/initiate

Begin the Trakt OAuth 2.0 authorization code flow. Returns a URL to redirect the user to for authorization.

curl http://localhost:8080/api/v1/trakt/oauth/initiate \
  -H "x-api-key: YOUR_KEY"

auth_url

string

Full Trakt authorization URL to open in a browser. Example: https://trakt.tv/oauth/authorize?response_type=code&client_id=....

Returns 404 if the Trakt service is not enabled or has not been configured with an API key.

GET /trakt/oauth/callback

Exchange the OAuth authorization code returned by Trakt for an access token. Riven stores the token in settings automatically.

code

string

required

The code query parameter returned by Trakt after the user grants access.

curl "http://localhost:8080/api/v1/trakt/oauth/callback?code=OAUTH_CODE" \
  -H "x-api-key: YOUR_KEY"

message

string

"OAuth token obtained successfully" on success.

Returns 400 if the code exchange fails, 404 if the Trakt API service is not found or no API key is configured.

Webhooks

POST /webhook/overseerr

Receive an Overseerr notification webhook and immediately add the requested media item to the Riven processing queue. Configure this URL in your Overseerr notification settings. Webhook URL to configure in Overseerr:

http://YOUR_RIVEN_HOST:8080/api/v1/webhook/overseerr

Riven accepts the full Overseerr webhook payload. Test notifications are acknowledged and logged without creating an item. All other notification types cause Riven to create and enqueue a new MediaItem.

success

boolean

Whether the webhook was processed successfully.

message

string|null

Error description when success is false.

Example success response

{
  "success": true
}

Overview

Endpoints

System API: Health, Stats, Logs, Debug, and Webhooks

Root

GET /

Health

GET /health

Services

GET /services

Statistics

GET /stats

Events

GET /events

Logs

GET /logs

POST /upload_logs

Debug bundle

POST /debug

Calendar

GET /calendar

Mount

GET /mount

VFS statistics

GET /vfs_stats

Downloader account info

GET /downloader_user_info

API key generation

POST /generateapikey

Trakt OAuth

GET /trakt/oauth/initiate

GET /trakt/oauth/callback

Webhooks

POST /webhook/overseerr

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Root

​GET /

​Health

​GET /health

​Services

​GET /services

​Statistics

​GET /stats

​Events

​GET /events

​Logs

​GET /logs

​POST /upload_logs

​Debug bundle

​POST /debug

​Calendar

​GET /calendar

​Mount

​GET /mount

​VFS statistics

​GET /vfs_stats

​Downloader account info

​GET /downloader_user_info

​API key generation

​POST /generateapikey

​Trakt OAuth

​GET /trakt/oauth/initiate

​GET /trakt/oauth/callback

​Webhooks

​POST /webhook/overseerr

Build docs developers (and LLMs) love

Root

GET /

Health

GET /health

Services

GET /services

Statistics

GET /stats

Events

GET /events

Logs

GET /logs

POST /upload_logs

Debug bundle

POST /debug

Calendar

GET /calendar

Mount

GET /mount

VFS statistics

GET /vfs_stats

Downloader account info

GET /downloader_user_info

API key generation

POST /generateapikey

Trakt OAuth

GET /trakt/oauth/initiate

GET /trakt/oauth/callback

Webhooks

POST /webhook/overseerr