Открытое API XMVP

загружаю спецификацию…

База/api/v1

АвторизацияAuthorization: Bearer <токен>

ФорматPOST + application/json

Если запрос составлен неверно

Сервер никогда не обрывает запрос молча. На любую ошибку приходит объяснение: что именно не так, жив ли сам эндпоинт и какая команда сработает. Из браузера то же самое открывается обычной страницей, в консоли и коде в виде JSON.

Поля ответаerror, message, hint, endpoint, service, docs, example

405метод не тот, нужен POST с JSON

404пути нет, в ответе список всех эндпоинтов и похожий вариант

401 и 403нет токена или нужен токен аккаунта

400 и 413тело не разобрано или больше лимита

429лимит частоты или суточного трафика

426путь канала принимает только постоянные соединения, обычный HTTP запрос отклоняется

410путь /ws без имени канала не обслуживается, в ответе список каналов

Живые каналы

Реалтайм работает на восьми каналах: каждый открывается отдельным постоянным соединением на свой путь и принимает только свои команды. Рукопожатие везде одинаковое: hello, потом sess с токеном, потом join в комнату. Машиночитаемая спецификация протокола: asyncapi.json.

room/ws/room комната, присутствие, пароли, список своих комнат

editor/ws/editor совместный редактор, бинарные кадры Yjs и awareness

upload/ws/upload выгрузка файлов чанками с докачкой

download/ws/download скачивание файлов и архива комнаты

files/ws/files дерево файлов, переименование, потоковые билеты

versions/ws/versions история версий комнаты

watch/ws/watch совместный просмотр видео

admin/ws/admin живая сводка панели администратора

Капча из своего клиента

Регистрация, сброс токена и вход анонима в комнату защищены капчей, а её виджет работает только в браузере. Клиент без интерфейса (скрипт, бот, консольная утилита) проходит проверку через бекенд: получает ссылку, человек открывает её в любом браузере, клиент забирает готовый пропуск.

1POST /captcha/start вернёт ticket и url

2покажи url пользователю: открыть в браузере, QR, строка в терминале

3человек проходит капчу на странице API, ничего вводить не нужно

4POST /captcha/result раз в 3 секунды, пока не придёт solved: true и captcha_pass

5передай captcha_pass в теле запроса или как captchaPass в команде join живого канала

Заявкаживёт 10 минут, потом 404 captcha_ticket_gone, нужна новая

Пропускживёт час, годится для любого числа входов в комнаты

Строгие операции/auth/register и /token/reset принимают пропуск один раз и только в первые 10 минут: на каждую своя заявка

Аккаунтыполучают captcha_pass сразу в /auth/session и /auth/whoami, заявка им нужна только для сброса токена

Капча выключена/captcha/start отвечает required: false, шаги 2–5 пропускаются