API, MCP и интеграции¶
Здесь — задачи для тех, кто подключает Рокет Хоум к своему коду, агенту или самодельному устройству. Владельцу дома они обычно не нужны: начните с Быстрый старт. Исключение — начало Подключение ИИ-агента: что даст дому ИИ-агент.
Вызвать API из своего приложения¶
Обобщённый API v2 работает по OAuth 2.0. Клиент регистрируется сам (Dynamic Client
Registration, POST /oauth/register), метаданные сервера — в
/.well-known/oauth-authorization-server. Доступ ограничивают scopes:
rh.profile:read, rh.structure:read (локации и комнаты), rh.devices:control,
rh.automations:read, rh.automations:write, rh.mqtt:connect (MQTT с управлением
устройствами), rh.mqtt:read (MQTT только для чтения). Пользователь может сузить
scope до локации или комнаты: rh.devices:control@location:{uuid}.
Лимит — 120 запросов в минуту на пользователя, общий для всех его клиентов. Сверх него API
отвечает 429 с заголовком Retry-After: повторяйте запрос не раньше, чем через указанное
число секунд.
Все эндпоинты, схемы и коды ответов — в справочнике API Рокет Хоум.
Подключить ИИ-агента (MCP)¶
MCP-сервер Рокет Хоум — https://ai.rocket-home.ru/mcp (Streamable HTTP). Агент видит
структуру дома, управляет устройствами и автоматизациями от вашего имени. Вход и ключи доступа —
на странице ai.rocket-home.ru через аккаунт rocket-home.ru.
Как выпустить токен агента, выбрать ему права и подключить Claude Code, Claude Desktop, Cursor или другой клиент — полная инструкция по подключению.
Документация для агентов¶
Любая страница этих доков доступна в markdown: запросите её обычный URL с заголовком
Accept: text/markdown или добавьте к нему суффикс .md
(/docs/usage/troubleshooting.html.md). Оглавление для агентов — /llms.txt
(llmstxt.org).
Получить MQTT-токен¶
Короткоживущий MQTT-JWT для своего клиента выдаёт GET /api/mqtt/v1/token (основная локация
пользователя); для конкретной локации — GET /api/mqtt/v1/locations/{location}/token. Под
scope rh.mqtt:connect токен управляет устройствами. Под rh.mqtt:read — только читает:
подписка на состояния работает, публиковать можно лишь запрос состояния в …/get, команды
в …/set брокер отклоняет. Если в гранте оба scope, действует rh.mqtt:connect. Постоянные
логин и пароль MQTT показаны в кабинете: Настройки → MQTT.
Подключить своё устройство¶
Устройство, которое само публикует состояние по MQTT, подключается к облаку через открытый
драйвер generic. Сквозной пример «от железа до панели» —
DIY-измеритель CO₂ на ESPHome.
Автоматизировать в Node-RED¶
Облачный Node-RED с нодами Рокет Хоум — Node-RED.
Ассистент в Telegram и MAX — права и управление.
Справочники¶
Подключение ИИ-агента — токены и права агентов, настройка клиентов, ошибки и инструменты MCP.
Язык автоматизаций — спецификация условий, шагов и версий.
Локальное исполнение — как автоматизация работает на хабе.
Словарь автоматизаций — термин ↔ подпись в интерфейсе ↔ значение в API.
- Подключение ИИ-агента
- Ассистент в мессенджере
- Язык автоматизаций
- Модель исполнения
- Предварительный запуск (готовность к времени)
- Расписание и часовой пояс
- Действия (
then_actions) - Отмена по событию (v16; авторский адрес — v18)
- Сообщение: уведомить, запросить подтверждение, запросить значения (v15)
- Снятый шаг
ask(v12) - Коридор поддержания (из пороговых триггеров)
- Группа как устройство: одна логика + фоновые задачи
- Плоскость автоматизаций на шине (ADR 0028)
- Свойство другого устройства (v22)
- Время как операнд (v10)
- Тип-модель
- Поверхностный синтаксис (грамматика, EBNF)
- Каноническая форма (AST) — краткий справочник
- Семантика операторов
- Параметры (schema_version 8)
- Регистры устройства: происхождение и шкала доступа
- «Запись» и «Чтение» логики группы (v39)
- Ветка «Событие устройства» (v36)
- Команда группе доходит до группы (v26)
- Ветка гашения (
on_stop) — свойство фоновой ЗАДАЧИ - Версионирование и расширяемость (SemVer)
- Локальное исполнение
- Словарь автоматизаций
- Node-RED