Как нейросети и агенты работают с Movie Planner

Версионированный HTTP API — префикс /v1 на бэкенде. Эта страница статическая (GitHub Pages). Живые эндпоинты API — на поддомене api.movie-planner.ru (Railway); так curl и скрипты получают обычный HTTP-ответ без GitHub Pages.

Позиционирование: Movie Planner — сервис, который превращает ИИ из «советчика фильмов» в реального кино-ассистента: планирование, напоминания, календарь, группы, билеты и Smart TV.

1. Что может делать ИИ через API

При валидном токене модель или агент может:

• читать профиль и контекст комнаты — GET /v1/me;
• смотреть и создавать планы просмотра — GET/POST /v1/plans;
• добавлять фильмы по Kinopoisk id или ссылке — POST /v1/movies;
• читать непросмотренное — GET /v1/library/unwatched;
• управлять группами — GET/POST /v1/groups;
• генерировать invite-ссылку в группу — POST /v1/groups/{chat_id}/invite;
• запускать просмотр на ТВ (если настроен агент) — POST /v1/tv/launch;
• работать с календарём: .ics, подписанные ссылки, Google — см. OpenAPI (пути …/calendar-links, …/google-calendar);
• прикреплять билеты к кино-плану — POST /v1/plans/{plan_id}/tickets (base64 изображение).

Полный контракт: OpenAPI YAML, кратко — /developer.

2. Как авторизоваться

Приватные методы /v1/* требуют заголовок:

Authorization: Bearer <токен>

Вариант A — сессия уже есть

Пользователь вошёл в приложение или веб-кабинет на movie-planner.ru: у клиента есть JWT или токен сайта. Передавать в ИИ-интеграцию только с согласия пользователя, не светить токены в публичных логах.

Вариант B — OAuth2 для внешнего приложения

1. Пользователь уже авторизован в Movie Planner.
2. POST /oauth/authorize с PKCE → получаете code.
3. POST /oauth/token с code_verifier → access_token.
4. Запросы с Authorization: Bearer <access_token>. В authorize можно указать scope (например profile.read plans.read movies.write).

Регистрация клиента OAuth — POST /oauth/clients (серверный секрет). Подробности на /developer.

3. Задачи, которые пользователь может поручить нейросети

• «Добавь фильм …» → POST /v1/movies
• «Запланируй просмотр на …» → POST /v1/plans
• «Что в непросмотренном?» → GET /v1/library/unwatched
• «Создай группу … и дай ссылку друзьям» → POST /v1/groups + POST /v1/groups/{chat_id}/invite
• «Открой на телевизоре …» → POST /v1/tv/launch
• «Прикрепи билет к плану» → POST /v1/plans/{id}/tickets
• «Дай ссылку на календарь» → GET /v1/plans/{id}/calendar-links и т.д.

Без токена — 401; при узком OAuth scope — 403 insufficient_scope.

4. Почему это сильнее обычного чата с ИИ

5. Репозитории и MCP

Бэкенд и черновики схем: репозиторий movie_planner_bot (docs/tool-schemas/). Локальный MCP: python -m moviebot.mcp_server с переменными MP_BASE_URL, MP_BEARER_TOKEN.

6. Быстрые ссылки