vidconf/docs/api

Документация API

VidConf REST + WebSocket API: аутентификация, профиль, динамические конференции, чат, администрирование, health check. Конференции создаются динамически — предустановленных комнат и бронирований нет (см. ADR-001).

Интерактивная документация

FastAPI автоматически генерирует интерактивные документы:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Аутентификация & авторизация

Полная документация: docs/api/auth.md

Эндпоинт	Метод	Описание
/api/v1/auth/registration-options	GET	Публичные опции регистрации (выбор команды)
/api/v1/auth/register	POST	Регистрация нового пользователя
/api/v1/auth/verify-email	POST	Подтверждение email по токену
/api/v1/auth/token	POST	OAuth2 вход (email + пароль) → access + refresh токены
/api/v1/auth/refresh	POST	Ротация refresh-токена → новый access-токен
/api/v1/auth/logout	POST	Отзыв refresh-токена

Профиль пользователя

Полная документация: docs/api/users.md

Эндпоинт	Метод	Описание
/api/v1/users/me	GET	Профиль текущего пользователя
/api/v1/users/me	PATCH	Обновить ФИО и команду
/api/v1/users/me/avatar	POST	Загрузить аватар (JPEG/PNG/WebP, ≤2 МБ)
/api/v1/users/me/avatar	DELETE	Удалить аватар
/api/v1/users	GET	Поиск пользователей для пикера участников

Справочник команд

Полная документация: docs/api/teams.md

Эндпоинт	Метод	Описание
/api/v1/teams	GET	Список всех команд (для выбора в профиле)

Для CRUD операций над командами см. Администраторский API.

LiveKit интеграция

Эндпоинт	Метод	Описание
/api/v1/livekit/webhook	POST	Приёмник webhook-событий от LiveKit

GET /api/health

Проверка доступности backend и зависимостей.

Request:

curl http://localhost:8000/api/health

Response (200 OK):

{
  "status": "ok",
  "db": true,
  "redis": true
}

---

Динамические конференции

Управление конференциями

Полная документация: docs/api/conferences.md

Эндпоинт	Метод	Описание
/api/v1/conferences	POST	Создать конференцию (мгновенную без scheduled_at или плановую)
/api/v1/conferences/my	GET	Мои конференции: закреплённые + предстоящие разовые
/api/v1/conferences/calendar	GET	Развёртка вхождений (occurrences) в диапазоне дат (≤62 дней)
/api/v1/conferences/resolve	GET	Найти конференцию по номеру или ссылке (публичный, rate limit 10/мин)
/api/v1/conferences/{id}/join	POST	Вход зарегистрированного пользователя (с пароль-опцион)
/api/v1/conferences/{id}/guest-join	POST	Вход гостем (публичный, rate limit, display_name обязателен)
/api/v1/conferences/{id}	PATCH	Изменить конференцию (владелец/администратор)
/api/v1/conferences/{id}	DELETE	Удалить конференцию (запрещено для активной)

Ключевые особенности (в отличие от прежней модели бронирования переговорных комнат, см. ADR-001):

• Конференция имеет 9-значный номер (вместо room + booking)
• Вход по номеру или постоянной ссылке (slug), без привязки к комнате
• Гости представляются (display_name + email опционально) и участвуют в пайплайне
• Закреплённые конференции могут повторяться (weekly/biweekly/monthly/every_n_days)
• Нет конкуренции за ресурсы → EXCLUDE constraint не используется, конфликты — на уровне бизнес-логики

---

Администраторский API

Полная документация: docs/api/admin.md

Эндпоинт	Метод	Описание
/api/v1/admin/conferences	GET	Список всех конференций с фильтрацией и пагинацией (только админ)
/api/v1/admin/conferences/{id}	PATCH	Изменить конференцию (только админ)
/api/v1/admin/conferences/{id}	DELETE	Удалить конференцию (только админ, запрещено для активной)
/api/v1/admin/conferences/{id}/invitations	POST	Поставить рассылку .ics-приглашений (202, асинхронно)
/api/v1/admin/users	GET	Список пользователей с пагинацией (только админ)
/api/v1/admin/users/{id}	PATCH	Изменить роль/блокировку/команду пользователя (только админ, запрет самоизменения роли/блокировки)
/api/v1/admin/teams	GET	Список всех команд (только админ)
/api/v1/admin/teams	POST	Создать команду (только админ, 409 при дубле названия)
/api/v1/admin/teams/{id}	PATCH	Переименовать команду (только админ)
/api/v1/admin/teams/{id}	DELETE	Удалить команду (только админ, у пользователей обнулится team_id)
/api/v1/admin/settings	GET	Текущие настройки инстанса (только админ)
/api/v1/admin/settings	PUT	Обновить настройки инстанса (только админ; AI-уровень/таймзона/домен регистрации валидируются)

Все эндпоинты требуют JWT токен администратора (403 иначе).

---

Чат конференции

Обмен сообщениями в реальном времени

Полная документация: docs/api/chat.md

Эндпоинт	Протокол	Описание
/api/v1/conferences/{id}/chat	WebSocket	Текстовый чат (auth по LiveKit-токену, история, broadcast через Redis pub/sub)

Особенности:

• Аутентификация на уровне протокола WS (первое сообщение {"type":"auth","token":<LiveKit-токен>})
• История: последние 50 сообщений открытой сессии конференции
• Участники: зарегистрированные пользователи + гости (с пометкой is_guest)
• Тоггл chat.enabled из настроек инстанса в БД, проверяется на каждом подключении
• Отправитель видит своё сообщение через pub/sub (echo)

Close-коды: 4401 (невалидный auth), 4403 (чужая комната), 4404 (чат выключен / конференция не найдена / завершена).

Frontend: JoinOut содержит chat_enabled для отображения/скрытия UI панели без рестарта.

---

Планируемый API

• Прямой доступ к транскрипту сеанса через API (GET /api/sessions/{id}/transcript) — сейчас фразы доступны только внутри пайплайна и итогового саммари, отдельного read-эндпоинта нет.

Транскрибация, суммаризация и рассылка саммари/приглашений уже реализованы асинхронно через Celery-воркеры (статус — pipeline_status в conference_sessions, см. workers/README.md).

---

Соглашения

Все timestamps в UTC:

"created_at": "2026-07-15T14:30:00Z"

Авторизация: JWT Bearer token в заголовке Authorization (для защищённых эндпоинтов)

Публичные эндпоинты (без auth):

• GET /api/v1/conferences/resolve — поиск по номеру/ссылке (rate limit)
• POST /api/v1/conferences/{id}/guest-join — вход гостем (rate limit)

CORS: Frontend настроен в dev-прокси (vite.config.ts: /api → localhost:8000)

Плагины: Конфигурация AI сервисов через config/plugins.yaml. См. docs/plugins/contracts.md.

---

Тестирование

# Health check
curl http://localhost:8000/api/health

# Swagger docs
open http://localhost:8000/docs

Полная спецификация — в Swagger UI/ReDoc (см. выше) и в файлах этого каталога.