разработчикам · API v1

API для своих плееров и ботов

Отправляйте прослушивания из любого плеера, Discord-бота или скрипта и забирайте статистику. Публичные GET-запросы работают без ключа.

Ключ

Для POST-запросов нужен ваш api_key. Никому его не показывайте: с ним можно писать в вашу историю.

Ключ показывается один раз — при регистрацииПотеряли? Выпустите новый, старый сразу перестанет работать.Выпустить новый

Эндпоинты

Метод	Путь	Что делает
POST	/api/scrobble	Отправить трек в историю. Нужен api_key.
GET	/api/user/:username	Профиль, аватар и что играет сейчас.
GET	/api/leaderboard	Топ слушателей по опыту.
GET	/api/public-stats	Общие цифры сайта: прослушивания, треки.
POST	/api/devices/code	Начать подключение устройства без ключа.
POST	/api/devices/token	Забрать ключ, когда пользователь разрешил.

Поля скроббла

api_key: обязательно; Ваш секретный ключ.
title: обязательно; Название трека.
artist: обязательно; Исполнитель.
source: обязательно; Откуда трек: discord_rpc, custom_script и т. п.
album: по желанию; Альбом.
duration: по желанию; Длина трека в секундах.
progress_sec: по желанию; Сколько секунд уже прослушано.
is_playing: по желанию; Играет ли трек прямо сейчас.
cover_url, track_url: по желанию; Ссылки на обложку и сам трек.

Подключение устройства

Если не хотите, чтобы пользователь вставлял ключ руками, подключите устройство по короткому коду — так работает наше расширение.

01Вызовите POST /api/devices/code с полем client_name и покажите пользователю user_code.
02Пользователь вводит код на странице /link и разрешает доступ.
03Опрашивайте POST /api/devices/token с device_code раз в interval секунд, пока статус pending. После подтверждения придёт api_key.

Примеры

curl -X POST https://api.music.vein.guru/api/scrobble \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ваш_ключ",
    "title": "Всё забрать",
    "artist": "Джизус",
    "source": "terminal"
  }'