Справочник API
TorrPlay предоставляет полнофункциональный RESTful API для программного управления. Полная спецификация OpenAPI доступна по адресу api/api.yaml.
Кроме того, ознакомиться с документацией API можно в Scalar.
Базовый URL
Все эндпоинты API задаются относительно:
http://localhost:8090Эндпоинты
Аутентификация
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /oauth/token | Получение JWT-токена администратора (Bearer auth) |
POST | /api/v1/tokens | Создание делегированного токена воспроизведения (scope: play) |
Основной API
| Метод | Эндпоинт | Описание |
|---|---|---|
GET | /api/v1/torrents | Получение списка всех торрентов |
POST | /api/v1/torrents | Добавление нового торрента |
POST | /api/v1/torrent-resolutions | Чтение удалённого торрент-файла без сохранения |
GET | /api/v1/torrents/{hash} | Получение метаданных торрента |
PATCH | /api/v1/torrents/{hash} | Обновление метаданных торрента |
DELETE | /api/v1/torrents/{hash} | Удаление торрента |
PUT | /api/v1/torrents/{hash}/preload | Запуск или обновление предзагрузки торрента |
GET | /api/v1/torrents/{hash}/preload | Получение статуса и прогресса буфера предзагрузки |
DELETE | /api/v1/torrents/{hash}/preload | Отмена предзагрузки |
GET | /api/v1/torrents/backup | Создание резервной копии торрентов и постеров |
POST | /api/v1/torrents/restore | Восстановление торрентов и постеров из резервной копии |
GET | /api/v1/stream/{hash} | Потоковая передача файла торрента |
HEAD | /api/v1/stream/{hash} | HEAD-запрос для файла, доступного для потоковой передачи |
GET | /api/v1/playlist | Генерация M3U-плейлиста для потоковой передачи |
GET | /api/v1/settings | Получение настроек приложения |
PATCH | /api/v1/settings | Обновление настроек приложения |
Протокол Stremio Addon
| Метод | Эндпоинт | Описание |
|---|---|---|
GET | /stremio/manifest.json | Манифест аддона Stremio |
GET | /stremio/{token}/manifest.json | Манифест аддона с авторизацией по токену в URL |
GET | /stremio/catalog/{type}/{id}.json | Просмотр каталога фильмов или сериалов |
GET | /stremio/meta/{type}/{id}.json | Получение метаданных и списка серий |
GET | /stremio/stream/{type}/{id}.json | Получение ссылок на потоковое воспроизведение |
GET | /stremio/play/{hash}/{fileIdx}/{filename} | Обработчик прямого воспроизведения с поддержкой Range-header |
Статистика
| Метод | Эндпоинт | Описание |
|---|---|---|
GET | /api/stats/memory | Получение общей статистики использования памяти |
GET | /api/stats/torrents/{hash} | Получение статистики по торренту |
Система
| Метод | Эндпоинт | Описание |
|---|---|---|
GET | /api/system/health | Проверка работоспособности |
GET | /api/system/info | Получение информации о приложении |
GET | /api/system/logs | Получение логов приложения — см. раздел Журналы |
GET | /api/system/metrics | Получение системных метрик — см. раздел Метрики |
GET | /metrics | Экспорт метрик Prometheus — см. раздел Метрики |
Совместимость с qBittorrent
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /api/v2/torrents/add | Добавление нового торрента (совместимо с qBittorrent) |
Совместимость с TorrServer
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /cache | Получение статистики кэша |
GET | /echo | Проверка состояния сервера |
GET | /play/{hash}/{index} | Потоковая передача содержимого торрента |
POST | /settings | Обновление настроек |
GET | /stream/{filename} | Потоковая передача или предварительная загрузка торрента |
POST | /torrents | Управление торрентами |
POST | /torrent/upload | Добавление нового торрента |
POST | /viewed | Управление тегами просмотра торрентов |
Потоковая передача
Для потоковой передачи файлов из торрента укажите хеш и URL-кодированный путь к файлу:
http://localhost:8090/api/v1/stream/{hash}?path={url_encoded_path}Если включена аутентификация, добавьте токен воспроизведения:
http://localhost:8090/api/v1/stream/{hash}?path={url_encoded_path}&token={playback_token}Пример запроса:
http://localhost:8090/api/v1/stream/dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c?path=Big.Buck.Bunny.1080p.mp4Эндпоинты GET и HEAD также принимают необязательный URL-кодированный параметр magnet. Он передаёт трекеры, через которые TorrPlay ищет пиров для торрента, которого ещё нет в библиотеке.
Предзагрузка
Запустите или замените предзагрузку торрента, указав индекс либо путь к файлу. Если не передать ни одно из этих полей, TorrPlay выберет файл с индексом 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 добавляет к началу и концу файла диапазон возле сохранённой позиции просмотра. Запрос также принимает file_path и необязательную magnet-ссылку в поле magnet.
Ответ содержит target_bytes, completed_bytes, progress, download_rate, active_peers, total_peers и один из следующих статусов:
| Статус | Значение |
|---|---|
idle | Для торрента нет предзагрузки |
queued | Ожидание свободного слота или памяти |
preloading | Загрузка выбранных диапазонов файла |
ready | Все запланированные диапазоны находятся в кэше |
failed | Не удалось зарезервировать память или торрент перестал получать данные |
evicted | Резерв освобождён для другой предзагрузки или после уменьшения лимита памяти |
Если воспроизведение не началось, предзагрузка со статусом ready хранится 10 секунд. После использования TorrPlay освобождает её, когда закроется последний поток чтения файла, включая оставленный открытым в ожидании следующего запроса. Конечный статус failed или evicted также доступен в течение 10 секунд.
Чтение удалённого торрент-файла
POST /api/v1/torrent-resolutions загружает файл .torrent по HTTP- или HTTPS-ссылке и возвращает его метаданные, не создавая запись в базе данных. Если торрент уже есть в библиотеке, эндпоинт вернёт сохранённые метаданные без изменений:
curl -X POST http://localhost:8090/api/v1/torrent-resolutions \
-H "Content-Type: application/json" \
-d '{"url":"https://indexer.example/download/example.torrent"}'Чтобы сохранить торрент в библиотеке, используйте POST /api/v1/torrents.
Аутентификация
При включённой аутентификации учётные данные необходимо указывать в каждом защищённом запросе. Эндпоинт выдачи токенов и проверка работоспособности доступны без аутентификации. Подробности в разделе Аутентификация.
Базовая аутентификация
Имя пользователя и пароль указываются в каждом защищённом запросе:
curl -u your-username:your-password http://localhost:8090/api/v1/torrentsТокен Bearer
Для защищённых эндпоинтов JWT-токен указывается в заголовке Authorization.
curl -H "Authorization: Bearer your-jwt-token" http://localhost:8090/api/v1/torrentsПолучение токена
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"Пример: добавление торрента
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"
}'