Scraping API: Find Torrents and Manage Scrape Sessions

The Scraping API exposes everything you need to find torrents for your media items, select the right files, and start the download. You can run a quick manual scrape and get back a ranked list of streams, open a stateful session to hand-pick files from a specific magnet link, or trigger Riven’s full auto-scrape pipeline. All routes are prefixed with /api/v1/scrape and require a valid API key.

Stream model

Scrape results are returned as a dictionary of infohash → Stream objects:

infohash

string

SHA-1 hex digest of the torrent info dictionary.

raw_title

string

The original release name string from the scraper source.

parsed_title

string

Cleaned title extracted by the RTN parser.

parsed_data

object

Full ParsedData object from RTN containing resolution, audio, codecs, seasons, episodes, and more.

rank

integer

RTN ranking score. Higher is better.

lev_ratio

float

Levenshtein similarity ratio between the parsed title and the item’s canonical title. Range 0–1.

is_cached

boolean

Whether the torrent is confirmed cached on the configured debrid service.

Scrape an item

GET /scrape

Retrieve a ranked list of torrent streams for a media item. Accepts an item identified by internal ID or any supported external ID. Pass stream=true to receive results as a Server-Sent Event stream as each scraper finishes.

item_id

integer

Internal database ID of the media item.

tmdb_id

string

TMDB ID of the item. Requires media_type=movie.

tvdb_id

string

TVDB ID of the item. Requires media_type=tv.

imdb_id

string

IMDb ID of the item (e.g. tt0133093).

media_type

string

movie or tv. Required when using tmdb_id or tvdb_id.

custom_title

string

Override the item title used for scraping. Changes are not persisted to the database.

custom_imdb_id

string

Override the IMDb ID used for scraping. Changes are not persisted.

ranking_overrides

string

JSON-encoded ranking override object. Example: {"resolutions": ["1080p", "2160p"]}.

stream

boolean

default:"false"

When true, results are sent as SSE events (text/event-stream) as each scraper completes rather than waiting for all scrapers to finish.

min_filesize_override

integer

Minimum file size in MB. Overrides the configured global minimum.

max_filesize_override

integer

Maximum file size in MB. Overrides the configured global maximum.

curl "http://localhost:8080/api/v1/scrape?item_id=42" \
  -H "x-api-key: YOUR_KEY"

Standard JSON response

{
  "message": "Manually scraped streams for item Breaking Bad S01",
  "streams": {
    "abc123def456": {
      "infohash": "abc123def456",
      "raw_title": "Breaking.Bad.S01.1080p.BluRay.x264",
      "parsed_title": "Breaking Bad",
      "parsed_data": { "resolution": "1080p", "codec": "x264" },
      "rank": 8450,
      "lev_ratio": 0.98,
      "is_cached": true
    }
  }
}

SSE streaming events (`stream=true`)

When stream=true the response is text/event-stream. Each data: line is a JSON-encoded ScrapeStreamEvent:

event

string

Event type. One of: start, progress, streams, complete, error.

service

string

Name of the scraper service that produced this event (e.g. Torrentio). null for start/complete events.

message

string

Human-readable status message.

streams

object

Dictionary of new infohash → Stream pairs found by this service. Present on streams and complete events.

total_streams

integer

Running total of unique streams found so far.

services_completed

integer

Number of scraper services that have finished.

total_services

integer

Total number of scraper services being queried.

Example SSE output

data: {"event":"start","message":"Starting scrape for Breaking Bad S01","total_services":3}

data: {"event":"streams","service":"Torrentio","streams":{"abc123":{"infohash":"abc123",...}},"total_streams":12,"services_completed":1,"total_services":3}

data: {"event":"progress","service":"Jackett","message":"Jackett completed for Breaking Bad S01","total_streams":12,"services_completed":2,"total_services":3}

data: {"event":"complete","message":"Scraping complete. Found 12 total streams.","total_streams":12,"services_completed":3,"total_services":3}

Manual scraping sessions

A scraping session lets you add a torrent manually using its magnet link. The workflow is:

Start session — validate the magnet, probe the torrent files, get a session_id.
Select files — tell the debrid service which file IDs to download.
Update attributes — map selected files to specific episodes (TV shows).
Complete session — finalize and trigger Riven’s download pipeline.

At any point you can abort to cancel and clean up the torrent.

POST /scrape/start_session

Start a manual scraping session for a specific magnet link. Validates that the torrent is cached on the debrid service and returns a parsed list of files.

magnet

string

required

Full magnet URI including the xt=urn:btih: component.

item_id

integer

Internal database ID of the target item.

tmdb_id

string

TMDB ID (use with media_type=movie).

tvdb_id

string

TVDB ID (use with media_type=tv).

imdb_id

string

IMDb ID.

media_type

string

movie or tv.

min_filesize_override

integer

Minimum file size in MB.

max_filesize_override

integer

Maximum file size in MB.

curl -X POST "http://localhost:8080/api/v1/scrape/start_session?magnet=magnet%3A%3Fxt%3Durn%3Abtih%3Aabc123&item_id=42" \
  -H "x-api-key: YOUR_KEY"

session_id

string

UUID identifying this session. Required for all subsequent session actions.

item_id

integer

Database ID of the associated item.

torrent_id

string|integer

Debrid service torrent ID.

torrent_info

object

Full torrent metadata from the debrid service.

parsed_files

object[]

Show ParsedFile fields

file_id

integer

Debrid service file ID.

filename

string

Original filename.

filesize

integer

File size in bytes.

download_url

string

Direct download URL if available.

parsed_metadata

object

PTT-parsed metadata for this file.

expires_at

string

ISO 8601 datetime when the session expires (5 minutes from creation).

POST /scrape/session/

Perform an action on an active scraping session.

session_id

string

required

Session UUID returned by POST /scrape/start_session.

Request body

action

string

required

One of: select_files, update_attributes, abort, complete.

files

object

Required for select_files. A map of file_id → DebridFile entries to select for download.

file_data

object

Required for update_attributes. Either a single DebridFile (movie) or a ShowFileData season→episode→file map (TV).

curl -X POST "http://localhost:8080/api/v1/scrape/session/SESSION_UUID" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "select_files",
    "files": {
      "4": {"filename": "show.s01e01.mkv", "filesize": 1073741824}
    }
  }'

Auto scrape

POST /scrape/auto

Trigger Riven’s full automatic scrape-and-download pipeline for an item. For TV shows you can optionally restrict scraping to specific season numbers. Request body

media_type

string

required

movie or tv.

item_id

integer

Internal database ID.

tmdb_id

string

TMDB ID (movies).

tvdb_id

string

TVDB ID (TV shows).

imdb_id

string

IMDb ID.

season_numbers

integer[]

For TV shows only. If provided, only these seasons are scraped; all others are paused.

ranking_overrides

object

Override ranking preferences for this scrape. Example: {"resolutions": ["2160p"]}.

min_filesize_override

integer

Minimum file size in MB.

max_filesize_override

integer

Maximum file size in MB.

curl -X POST http://localhost:8080/api/v1/scrape/auto \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_type": "movie", "tmdb_id": "550"}'

Parse torrent titles

POST /scrape/parse

Parse an array of raw torrent title strings using the PTT/RTN parser. Returns structured metadata for each title. Request body A JSON array of strings:

["Breaking.Bad.S01E01.1080p.BluRay.x264-GROUP", "Inception.2010.4K.HDR.DV.HEVC"]

curl -X POST http://localhost:8080/api/v1/scrape/parse \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '["Breaking.Bad.S01E01.1080p.BluRay.x264-GROUP"]'

Example response

{
  "message": "Parsed torrent titles",
  "data": [
    {
      "raw_title": "Breaking.Bad.S01E01.1080p.BluRay.x264-GROUP",
      "title": "Breaking Bad",
      "season": 1,
      "episode": [1],
      "resolution": "1080p",
      "source": "BluRay",
      "codec": "x264",
      "group": "GROUP"
    }
  ]
}

Overseerr requests

POST /scrape/overseerr/requests

Fetch pending requests from Overseerr and add any that are not already in the Riven database to the processing queue.

filter

string

Overseerr request status filter. One of: all, approved, available, pending, processing, unavailable, failed, deleted, completed.

take

integer

default:"100000"

Maximum number of requests to fetch from Overseerr.

curl -X POST "http://localhost:8080/api/v1/scrape/overseerr/requests?filter=approved" \
  -H "x-api-key: YOUR_KEY"

Returns 412 if the Overseerr service is not enabled or not initialized.

Overview

Endpoints

Scraping API: Find Torrents and Manage Scrape Sessions

Stream model

Scrape an item

GET /scrape

SSE streaming events (`stream=true`)

Manual scraping sessions

POST /scrape/start_session

POST /scrape/session/

Auto scrape

POST /scrape/auto

Parse torrent titles

POST /scrape/parse

Overseerr requests

POST /scrape/overseerr/requests

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Stream model

​Scrape an item

​GET /scrape

​SSE streaming events (stream=true)

​Manual scraping sessions

​POST /scrape/start_session

​POST /scrape/session/

​Auto scrape

​POST /scrape/auto

​Parse torrent titles

​POST /scrape/parse

​Overseerr requests

​POST /scrape/overseerr/requests

Build docs developers (and LLMs) love

Stream model

Scrape an item

GET /scrape

SSE streaming events (`stream=true`)

Manual scraping sessions

POST /scrape/start_session

POST /scrape/session/

Auto scrape

POST /scrape/auto

Parse torrent titles

POST /scrape/parse

Overseerr requests

POST /scrape/overseerr/requests