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.

The Items API is the primary interface for your media library. It lets you add movies and shows by external ID, search and filter the entire collection, control item lifecycle states (pause, retry, reset, remove), and inspect or manage the cached torrent streams associated with each item. All routes are prefixed with /api/v1/items and require a valid API key.

​
States

​
GET /items/states

Returns the list of all valid item state names with a success flag. Use these values as filters in GET /items. 
curl http://localhost:8080/api/v1/items/states \
  -H "x-api-key: YOUR_KEY"
​
success
boolean
true when the request succeeded.
​
states
string[]
List of state name strings, e.g. Requested, Indexed, Scraped, Downloaded, Symlinked, Completed, Failed, Paused, Unreleased.
Example response 
{
  "success": true,
  "states": ["Requested", "Indexed", "Scraped", "Downloaded", "Symlinked", "Completed", "Failed", "Paused", "Unreleased"]
}

​
List and search items

​
GET /items

Fetch a paginated, filterable list of media items. Supports full-text search by title, lookup by external ID, state filtering, media-type filtering, and sort ordering.
​
limit
integer
default:"50"
Number of items per page. Minimum: 1.
​
page
integer
default:"1"
Page number. Minimum: 1.
​
search
string
Search by title (substring match) or by external ID. Prefix with tt for IMDb IDs, tmdb_ for TMDB, or tvdb_ for TVDB. Example: tt0133093, tmdb_550, tvdb_81189.
​
states
string[]
Filter by one or more states. Accepted values are those returned by GET /items/states. Pass the special value All to skip state filtering.
​
type
string[]
Filter by media type. Accepted values: movie, show, season, episode, anime.
​
sort
string[]
Sort order. Accepted values: title_asc, title_desc, date_asc, date_desc. Only one sort per dimension (title or date) is allowed. Defaults to date_desc.
​
extended
boolean
default:"false"
Include extended item details in each object.
curl "http://localhost:8080/api/v1/items?search=breaking+bad&type=show" \
  -H "x-api-key: YOUR_KEY"
​
success
boolean
Whether the request succeeded.
​
items
object[]
Array of media item objects.
​
page
integer
Current page number.
​
limit
integer
Items per page.
​
total_items
integer
Total matching items across all pages.
​
total_pages
integer
Total number of pages.

​
Add items

​
POST /items/add

Add one or more items to the processing queue by TMDB ID (for movies) or TVDB ID (for TV shows). Duplicate entries are silently ignored. Request body
​
tmdb_ids
string[]
List of TMDB IDs to add as movies. Only used when media_type is movie.
​
tvdb_ids
string[]
List of TVDB IDs to add as TV shows. Only used when media_type is tv.
​
media_type
string
required
Must be movie or tv.
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"}'
Example response 
{
  "message": "Added 1 item(s) to the queue"
}

​
Get a single item

​
GET /items/

Fetch one media item by its internal numeric ID, TMDB ID, or TVDB ID.
​
id
string
required
The item identifier. For media_type=item this is the numeric database ID; for movie use the TMDB ID string; for tv use the TVDB ID string.
​
media_type
string
required
item, movie, or tv. Determines how id is interpreted.
​
extended
boolean
default:"false"
Return extended item details.
curl "http://localhost:8080/api/v1/items/42?media_type=item" \
  -H "x-api-key: YOUR_KEY"

​
Reset items

​
POST /items/reset

Reset one or more items back to the Indexed state so they re-enter the scraping pipeline. Blacklists the currently active stream before resetting. Triggers a media-server library refresh when an updater service is configured. Request body
​
ids
string[]
required
List of internal numeric item IDs (as strings) to reset. Minimum 1 item.
curl -X POST http://localhost:8080/api/v1/items/reset \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["42", "43"]}'
​
message
string
Human-readable summary.
​
ids
integer[]
IDs that were processed.

​
Retry items

​
POST /items/retry

Re-add specific items to the processing queue. Request body
​
ids
string[]
required
List of item IDs to retry.
curl -X POST http://localhost:8080/api/v1/items/retry \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["42"]}'

​
POST /items/retry_library

Retry all failed and incomplete items in the library in one call. No request body is required. 
curl -X POST http://localhost:8080/api/v1/items/retry_library \
  -H "x-api-key: YOUR_KEY"
​
message
string
Summary including the number of retried items.
​
ids
integer[]
IDs that were queued for retry.

​
Remove items

​
DELETE /items/remove

Permanently remove one or more movies or shows from the database. Cancels active jobs, deletes the corresponding Overseerr request if present, removes the item from the VFS, and triggers a media-server library refresh.
Only movie and show items can be removed. Attempting to remove a season or episode directly returns 400 Bad Request.
Request body
​
ids
string[]
required
List of item IDs to remove.
curl -X DELETE http://localhost:8080/api/v1/items/remove \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["42"]}'
​
message
string
Human-readable summary.
​
ids
integer[]
IDs that were removed.

​
Streams

Each item tracks a list of candidate torrent streams. The following endpoints let you inspect and manage those streams.

​
GET /items//streams

Retrieve all active and blacklisted streams cached for an item.
​
item_id
integer
required
Internal database ID of the media item.
curl http://localhost:8080/api/v1/items/42/streams \
  -H "x-api-key: YOUR_KEY"
​
message
string
Status message.
​
streams
object[]
Active (non-blacklisted) streams.
​
blacklisted_streams
object[]
Streams that have been blacklisted for this item.

​
POST /items//streams//blacklist

Blacklist a specific stream so that Riven will not attempt to download it again for this item.
​
item_id
integer
required
Database ID of the media item.
​
stream_id
integer
required
Database ID of the stream.
curl -X POST http://localhost:8080/api/v1/items/42/streams/7/blacklist \
  -H "x-api-key: YOUR_KEY"

​
POST /items//streams//unblacklist

Remove a stream from the blacklist, allowing it to be selected again. 
curl -X POST http://localhost:8080/api/v1/items/42/streams/7/unblacklist \
  -H "x-api-key: YOUR_KEY"

​
POST /items//streams/reset

Clear all streams (active and blacklisted) for an item so fresh scrape results can be stored. 
curl -X POST http://localhost:8080/api/v1/items/42/streams/reset \
  -H "x-api-key: YOUR_KEY"

​
Pause and unpause

​
POST /items/pause

Pause one or more items. Paused items are skipped by the processing pipeline until explicitly unpaused. Request body
​
ids
string[]
required
List of item IDs to pause.
curl -X POST http://localhost:8080/api/v1/items/pause \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["42", "43"]}'

​
POST /items/unpause

Resume processing for paused items. Request body
​
ids
string[]
required
List of item IDs to unpause.
curl -X POST http://localhost:8080/api/v1/items/unpause \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["42"]}'
​
message
string
Status message.
​
ids
integer[]
IDs that were processed.

​
Reindex

​
POST /items/reindex

Force an item back through the composite indexer to pick up new seasons, episodes, or corrected metadata. Requires exactly one of the identifier fields. Request body
​
item_id
integer
Internal database ID.
​
tvdb_id
string
TVDB ID string.
​
tmdb_id
string
TMDB ID string.
​
imdb_id
string
IMDb ID string (e.g. tt0944947).
curl -X POST http://localhost:8080/api/v1/items/reindex \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_id": 42}'

​
Aliases

​
GET /items//aliases

Retrieve all known title aliases for an item (alternative titles from metadata providers).
​
item_id
integer
required
Internal database ID of the media item.
curl http://localhost:8080/api/v1/items/42/aliases \
  -H "x-api-key: YOUR_KEY"
​
aliases
object
Dictionary mapping locale codes to a list of alternative title strings. null if none are stored.
Example response 
{
  "aliases": {
    "en": ["Fight Club"],
    "de": ["Fight Club"]
  }
}

​
Metadata

​
GET /items//metadata

Return all stored metadata for an item. The response follows the MediaMetadata model from the indexer.
​
item_id
integer
required
Internal database ID of the media item.
curl http://localhost:8080/api/v1/items/42/metadata \
  -H "x-api-key: YOUR_KEY"
Returns 404 if no metadata entry exists for the item yet.

Build docs developers (and LLMs) love

Get started for freeTalk to us