HTTP API SoundVault.

Адрес и авторизация

Используй базовый HTTPS-адрес своей установки. API в основном расположен под /api/; вход выполняется через POST /login. Авторизация — сессионная cookie, которую нужно сохранять и передавать в последующих запросах.

curl --cookie-jar cookies.txt --request POST https://music.example.com/login   --header 'Content-Type: application/json'   --data '{"username":"user","password":"YOUR_PASSWORD"}'

curl --cookie cookies.txt https://music.example.com/api/me

Защити файл cookies от посторонних. Успешный JSON-вход возвращает {"ok":true,"is_admin":false}. Неверные данные — HTTP 401; частые попытки входа ограничиваются.

Для изменяющих запросов к API передавай X-Requested-With: XMLHttpRequest. Исключения: вход и межсерверный протокол федерации. Выход в текущем коде — GET /logout, после него сервер перенаправляет на вход.

Состояние и версии

GET /api/health проверяет приложение и базу: статус 200 при нормальной работе, 503 при деградации базы. GET /api/capabilities возвращает публичные сведения о возможностях.

Поля могут отличаться между версиями. Клиент должен обрабатывать отсутствующие поля и null. Текущий лендинг запрашивает capabilities при открытии страницы.

Библиотека и аудиопоток

curl --cookie cookies.txt --get   --data-urlencode 'folder=public/Artist/Album'   https://music.example.com/api/tracks

curl --cookie cookies.txt --header 'Range: bytes=0-1023'   --output fragment.bin https://music.example.com/api/stream/123

Пути кодируй как URL-компоненты. Идентификатор трека может быть строкой peer://…; не считай все идентификаторы числами. Скрытые папки исключаются из обычного фильтра all.

Примеры изменения данных

Создание собственного плейлиста:

curl --cookie cookies.txt --request POST https://music.example.com/api/playlists   --header 'Content-Type: application/json'   --header 'X-Requested-With: XMLHttpRequest'   --data '{"name":"Вечерняя коллекция"}'

Ответ содержит ok и объект playlist. Запуск сканирования своей области:

curl --cookie cookies.txt --request POST https://music.example.com/api/scan_jobs   --header 'Content-Type: application/json'   --header 'X-Requested-With: XMLHttpRequest'   --data '{"scope":"user","folder":""}'

Для полной библиотеки требуется scope admin и роль администратора. Состояние задания доступно через GET /api/scan_jobs/<id>. Файлы загружаются multipart-запросом на POST /api/files/upload; лимиты и режимы конфликтов доступны в capabilities.

Доступ и ошибки

Большинство пользовательских маршрутов требуют сессию. Административные операции дополнительно проверяют роль. Для файлов и музыки проверяются права на соответствующий объект. Межсерверные маршруты /api/peer/ используют подписи Ed25519; получение приглашения не заменяет подтверждение связи.

{"ok":false,"error":"Папка не найдена","code":"not_found"}

Ответы об успешном чтении не всегда имеют поле ok. Ошибки облака, требующие повторного подключения, могут возвращать 400 вместо 401; проверяй поле code, чтобы не сбрасывать сессию SoundVault.

Справочник маршрутов

Список сформирован из декораторов маршрутов исходного кода 7 октября 2026 года. Разверни нужный раздел. Параметры в угловых скобках заменяются значениями и кодируются в URL. Это перечень путей и методов; примеры основных контрактов приведены выше.