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 exposes a versioned HTTP API under the path /api/v1 that lets you manage every aspect of the media pipeline: adding items to the library, tuning configuration, triggering scrapes, streaming real-time events, and monitoring system health. All requests and responses use JSON, and every endpoint except the root health-check requires API key authentication.

​
Base URL

http://localhost:8080/api/v1
Riven listens on port 8080 by default. If you have changed the port in your deployment, substitute that port number throughout all examples.

​
Interactive documentation

Riven ships with two built-in API explorer interfaces:
InterfaceURL
Scalar UI (interactive)http://localhost:8080/scalar
Raw OpenAPI JSON schemahttp://localhost:8080/openapi.json

​
Authentication

All endpoints except GET /api/v1/ require a valid API key. Pass your key using one of these methods:
  • Header: x-api-key: YOUR_KEY
  • Bearer token: Authorization: Bearer YOUR_KEY
  • Query parameter: ?api_key=YOUR_KEY
See the Authentication page for full details and curl examples.

​
Response format

All successful responses return JSON. The exact schema varies by endpoint; most write operations return a MessageResponse: 
{
  "message": "Operation completed successfully"
}

​
Error format

All error responses follow the same shape: 
{
  "detail": "A human-readable error message"
}
Common HTTP status codes:
CodeMeaning
200 OKRequest succeeded
400 Bad RequestInvalid parameters or request body
401 UnauthorizedMissing or invalid API key
404 Not FoundResource does not exist
412 Precondition FailedRequired service not initialized
500 Internal Server ErrorUnexpected server-side error

​
Endpoint groups

Items

Add, search, reset, retry, pause, and remove media items in your library. Manage per-item streams and blacklists.

Settings

Read and update every configuration value in AppModel. Export and import full settings files.

Scraping

Trigger manual or automatic scrapes, manage scraping sessions, parse torrent titles, and sync Overseerr requests.

Streaming

Subscribe to Server-Sent Event streams for live log output and state changes. Proxy media files from debrid providers.

System

Health checks, aggregated library statistics, log retrieval, debug bundles, Trakt OAuth, and more.

​
Quick start

The following example walks through the most common first steps: checking that the API is reachable, verifying authentication, and adding a movie. 
# 1. Check root (no auth required)
curl http://localhost:8080/api/v1/

# 2. Verify auth is working
curl http://localhost:8080/api/v1/health \
  -H "x-api-key: YOUR_KEY"

# 3. Add a movie by TMDB ID
curl -X POST http://localhost:8080/api/v1/items/add \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tmdb_ids": ["550"], "media_type": "movie"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us