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

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

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

FastAPI автоматически генерирует интерактивные документы:
- **Swagger UI:** `http://localhost:8000/docs`
- **ReDoc:** `http://localhost:8000/redoc`
- **OpenAPI JSON:** `http://localhost:8000/openapi.json`

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

**[Полная документация: docs/api/auth.md](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](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](teams.md)**

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

**Для CRUD операций над командами см. [Администраторский API](./admin.md#команды).**

## LiveKit интеграция

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

## GET /api/health

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

**Request:**
```bash
curl http://localhost:8000/api/health
```

**Response (200 OK):**
```json
{
  "status": "ok",
  "db": true,
  "redis": true
}
```

---

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

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

**[Полная документация: docs/api/conferences.md](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](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](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](../../workers/README.md)).

---

## Соглашения

**Все timestamps в UTC:**
```json
"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](../plugins/contracts.md).

---

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

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

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

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