Skip to content
Documentation
API Reference

API Reference

TorrPlay provides a comprehensive RESTful API for programmatic control. The full OpenAPI specification is available at api/api.yaml.

You can also interact with the API documentation using Scalar.

Base URL

All API endpoints are relative to:

http://localhost:8090

Endpoints

Authentication

MethodEndpointDescription
POST/oauth/tokenObtain a JWT admin token (Bearer auth)
POST/api/v1/tokensCreate a scoped playback token

Core API

MethodEndpointDescription
GET/api/v1/torrentsList all torrents
POST/api/v1/torrentsAdd a new torrent
POST/api/v1/torrent-resolutionsResolve a remote torrent without saving it
GET/api/v1/torrents/{hash}Get torrent metadata
PATCH/api/v1/torrents/{hash}Update torrent metadata
DELETE/api/v1/torrents/{hash}Delete a torrent
PUT/api/v1/torrents/{hash}/preloadStart or update torrent preloading
GET/api/v1/torrents/{hash}/preloadGet torrent preload status and buffer
DELETE/api/v1/torrents/{hash}/preloadCancel torrent preload
GET/api/v1/torrents/backupBackup torrents and posters
POST/api/v1/torrents/restoreRestore torrents and posters
GET/api/v1/stream/{hash}Stream a torrent file
HEAD/api/v1/stream/{hash}HEAD request for a streamable file
GET/api/v1/playlistGenerate an M3U playlist for streaming
GET/api/v1/settingsGet application settings
PATCH/api/v1/settingsUpdate application settings

Stremio Addon Protocol

MethodEndpointDescription
GET/stremio/manifest.jsonAddon manifest descriptor
GET/stremio/{token}/manifest.jsonAuthenticated addon manifest descriptor
GET/stremio/catalog/{type}/{id}.jsonBrowse movies or series catalog
GET/stremio/meta/{type}/{id}.jsonRetrieve item details and season/episode lists
GET/stremio/stream/{type}/{id}.jsonFetch stream playback links
GET/stremio/play/{hash}/{fileIdx}/{filename}Direct media stream handler

Statistics

MethodEndpointDescription
GET/api/stats/memoryGet global memory statistics
GET/api/stats/torrents/{hash}Get torrent statistics

System

MethodEndpointDescription
GET/api/system/healthHealth check
GET/api/system/infoGet application information
GET/api/system/logsGet recent application logs — see Logs
GET/api/system/metricsGet system metrics — see Metrics
GET/metricsPrometheus metrics export endpoint — see Metrics

qBittorrent Compatibility

MethodEndpointDescription
POST/api/v2/torrents/addAdd a new torrent (qBittorrent compatible)

TorrServer Compatibility

MethodEndpointDescription
POST/cacheGet cache statistics
GET/echoServer status check
GET/play/{hash}/{index}Stream torrent content
POST/settingsUpdate settings
GET/stream/{filename}Stream or preload torrent
POST/torrentsManage torrents
POST/torrent/uploadAdd a new torrent
POST/viewedManage torrent view tags

Streaming

Stream files from a torrent using the hash and URL-encoded file path:

http://localhost:8090/api/v1/stream/{hash}?path={url_encoded_path}

If authentication is enabled, append a scoped playback token:

http://localhost:8090/api/v1/stream/{hash}?path={url_encoded_path}&token={playback_token}

Example:

http://localhost:8090/api/v1/stream/dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c?path=Big.Buck.Bunny.1080p.mp4

The GET and HEAD stream endpoints also accept an optional URL-encoded magnet query parameter. It provides trackers for finding peers when the torrent has not been saved in TorrPlay.

Preloading

Start or replace the preload for a torrent using a file index or path. If both are omitted, TorrPlay selects file index 0:

curl -X PUT http://localhost:8090/api/v1/torrents/{hash}/preload \
  -H "Content-Type: application/json" \
  -d '{
    "file_index": 0,
    "playback_position_seconds": 900
  }'

playback_position_seconds asks the streaming engine to cache a window around a saved playback position in addition to the file’s head and tail. The request also accepts file_path and an optional magnet URI.

The response reports target_bytes, completed_bytes, progress, download_rate, active_peers, total_peers, and one of these states:

StatusMeaning
idleNo preload is registered for the torrent
queuedWaiting for a preload slot or enough memory
preloadingDownloading the requested file ranges
readyAll planned ranges are cached
failedThe preload could not reserve memory or stopped receiving data
evictedIts reservation was reclaimed for another preload or a smaller limit

An unread ready preload remains cached for 10 seconds. After playback uses it, TorrPlay releases it when the file’s last active or lingering reader closes. A terminal failed or evicted status is also retained for 10 seconds.

Resolving a Remote Torrent

POST /api/v1/torrent-resolutions downloads a .torrent file from an HTTP or HTTPS URL and resolves its metadata without saving a database record. If the torrent is already in the library, the endpoint returns its stored metadata unchanged:

curl -X POST http://localhost:8090/api/v1/torrent-resolutions \
  -H "Content-Type: application/json" \
  -d '{"url":"https://indexer.example/download/example.torrent"}'

Use POST /api/v1/torrents when the torrent should remain in the library.

Authentication

When authentication is enabled, include credentials with each protected request. The token endpoint and health check are public. See Authentication for details.

Basic Auth

Send username and password with each protected request:

curl -u your-username:your-password http://localhost:8090/api/v1/torrents

Bearer Token

Include the JWT token in the Authorization header for protected endpoints.

curl -H "Authorization: Bearer your-jwt-token" http://localhost:8090/api/v1/torrents

Obtaining a Token 

curl -X POST http://localhost:8090/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=your-username&password=your-password"

Example: Adding a Torrent 

curl -X POST http://localhost:8090/api/v1/torrents \
  -H "Content-Type: application/json" \
  -d '{
    "magnet": "magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c&dn=Big+Buck+Bunny"
  }'
Last updated on
Installers & Desktop AppsAuthentication