API обзор

Публичные endpoint группы

Prefix	Сервис	Описание
/api/v1/auth	auth	Регистрация, login, guest, Telegram, admin OTP
/api/v1/sessions	session	CRUD сессий, join, participants
/api/v1/games	game-runtime	Actions, state, history
/api/v1/admin	admin	Логи игр, списки (admin JWT)
/api/v1/media	media	Render, assets
/ws/v1	realtime	WebSocket

REST (ключевые)

Auth

Method	Path	Описание
POST	/auth/guest	Guest token
POST	/auth/register	Email регистрация
POST	/auth/login	JWT
POST	/auth/telegram	Telegram Login verify
POST	/auth/refresh	Refresh token
POST	/auth/admin/otp/request	Admin OTP (bot only)
POST	/auth/admin/otp/verify	Admin login → JWT

Admin (requires admin JWT)

Method	Path	Описание
GET	/admin/games	Список игр с фильтрами
GET	/admin/games/{id}	Метаданные игры
GET	/admin/games/{id}/log	Полный timeline
GET	/admin/sessions	Список сессий
GET	/admin/sessions/{id}/games	Игры сессии

Sessions

Method	Path	Описание
POST	/sessions	Создать сессию
GET	/sessions/{id}	Детали
POST	/sessions/join	Join по коду
POST	/sessions/{id}/games	Старт игры
DELETE	/sessions/{id}/participants/{pid}	Kick
POST	/sessions/{id}/close	Закрыть

Games

Method	Path	Описание
GET	/games/{id}/state	Текущий state
POST	/games/{id}/actions	Submit action
GET	/games/{id}/audit	Лог ходов (admin JWT)

Media

Method	Path	Описание
GET	/media/render/{game_id}	PNG/WebP поля

WebSocket

WS /ws/v1?token=<jwt_or_guest>

Client → Server

{ "type": "subscribe", "topic": "game:{game_id}" }
{ "type": "ping" }

Server → Client

{
  "type": "game.state_changed",
  "game_id": "...",
  "state": {},
  "view": {},
  "timestamp": "2026-06-07T12:00:00Z"
}

NATS topics (internal)

Topic	Publisher	Subscribers
session.created	session	realtime, bot
session.closed	session	game, bot
participant.joined	session	realtime, bot
game.started	game-runtime	realtime, bot, media
game.state_changed	game-runtime	realtime, bot
game.finished	game-runtime	session, realtime, bot

Аутентификация

Header	Значение
Authorization	Bearer <jwt> или Guest <guest_token>
Idempotency-Key	UUID для POST actions

OpenAPI

Полный черновик: openapi-draft.yaml

Версионирование

• Текущая: v1
• Deprecation: Sunset header за 90 дней