# API, которые использует студия

Студия = редактор игр. Дёргает много API: загрузка моделей, сохранение проектов, публикация, ассеты, админ-функции. Этот документ — полный список.

## Базовый URL

В prod:    `https://api.rublox.pro` (alias на `minecraftia-school.ru/api-storys`)
В dev:     `https://dev-api.rublox.pro` (staging)
Локально:  `http://localhost:8674` (storys-микросервис)

## Эндпоинты — список

### Проекты (CRUD)

| Method | Path | Когда |
|---|---|---|
| GET | `/kubikon3d/projects/<id>` | при открытии проекта в редакторе |
| POST | `/kubikon3d/projects` | при сохранении нового проекта |
| PUT | `/kubikon3d/projects/<id>` | при auto-save (каждые 60с) и при manual-save |
| DELETE | `/kubikon3d/projects/<id>` | юзер удалил свой проект |
| GET | `/kubikon3d/my-projects` | страница «Мои проекты» |
| POST | `/kubikon3d/projects/<id>/publish` | юзер жмёт «Опубликовать» |

**Размер `project_data` JSON:** обычно 100 КБ - 5 МБ. Лимит на бэке — **20 МБ** (settings, может меняться). Если проект больше — split на несколько (НЕ реализовано пока).

### Модели и ассеты

| Method | Path | Когда |
|---|---|---|
| GET | `/kubikon3d/models/public` | при открытии редактора, список общих GLB-моделей |
| GET | `/kubikon3d/models/mine` | панель «Мои модели» |
| GET | `/kubikon3d/models/<id>` | при первом упоминании модели в проекте |
| POST | `/kubikon3d/models` | юзер залил свою GLB-модель |
| DELETE | `/kubikon3d/models/<id>` | юзер удалил свою |

### Лента и поиск (как в плеере)

| Method | Path | Когда |
|---|---|---|
| GET | `/kubikon3d/feed` | главная редактора |
| GET | `/kubikon3d/trending` | главная |
| GET | `/kubikon3d/search?q=...` | поиск чужих проектов (для копирования идей) |
| GET | `/kubikon3d/collections` | секции |
| GET | `/kubikon3d/top-authors` | топ авторов |
| GET | `/kubikon3d/events` | мероприятия |

### Скины и аватары

| Method | Path | Когда |
|---|---|---|
| GET | `/kubikon3d/rublox/equipped-skin/<user_id>` | превью аватара текущего юзера в редакторе |
| GET | `/kubikon3d/rublox/owned-skins` | панель «Скины» |
| POST | `/kubikon3d/rublox/equipped-skin` | юзер сменил скин |

### Материалы для дизайнера

| Method | Path | Когда |
|---|---|---|
| GET | `/api-storys/designer/materials/list` | панель «Материалы» — текстуры и материалы для блоков |

### Чат и комментарии

| Method | Path | Когда |
|---|---|---|
| POST | `/kubikon3d/chat/<game_id>` | юзер пишет сообщение в чат своей игры (preview) |

### Telemetry (как в плеере)

| Method | Path | Когда |
|---|---|---|
| POST | `/kubikon3d/play/heartbeat` | при тесте игры через Play в редакторе |
| POST | `/kubikon3d/activity` | вход/выход в тестовый Play |
| POST | `/kubikon3d/perf-log` | при просадке FPS в тестовом Play |
| POST | `/kubikon3d/bug-reports` | юзер жмёт «Сообщить о баге» |
| POST | `/kubikon3d/reports` | репорт на чужой проект (из поиска) |

### Админка (для роли admin)

Все `/kubikon3d/admin/*` доступны только админам. Не админ → 403.

Список — см. [rublox-player/API_USAGE.md#админка](../rublox-player/API_USAGE.md). Студия использует тот же набор, что и плеер.

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

JWT в заголовке `Authorization: Bearer <token>`. Получение — через `/api-user/auth/login` (см. [rublox-player/API_USAGE.md#аутентификация](../rublox-player/API_USAGE.md#аутентификация)).

## Особенности студии vs плеера

- **Студия дополнительно** имеет CRUD на `/projects` (плеер только читает).
- **Студия загружает модели**: POST `/models` с multipart/form-data. Лимит 50 МБ на файл.
- **Auto-save**: студия каждые 60 секунд молча шлёт `PUT /projects/<id>`. Без этого проекты теряются при сбое браузера.
- **Conflict resolution**: если двое редактируют один проект, бэк возвращает 409 на PUT. Студия показывает диалог «Кто-то открыл проект параллельно, перезагрузить?».

## Изменения API

**Breaking changes** (изменение сигнатур, удаление полей) — объявление в `#разработка` за 48 часов + запись в `API_CHANGELOG.md` админ-репо.

## Контакты

- Issue tracker: https://git.rublox.pro/rublox/studio/issues
- Чат: `#разработка` на https://team.rublox.pro