{ "openapi": "3.0.3", "info": { "title": "Kaleo API", "version": "2026-10-08", "description": "Kaleo AI предоставляет веб-API для управления вашими потоковыми сессиями, получения аналитики зрителей и мониторинга устройств Kaleo Connect. Вы можете использовать наше API для интеграции с вашими пользовательскими AVL-контроллерами и рабочими процессами по мере необходимости.\n\nЧтобы начать, следуйте инструкциям ниже, чтобы получить ключ API, найти ID вашей церкви и аутентифицировать ваши запросы.\n\n## Получение ключа API\n\n1. Перейдите на страницу [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.\n2. Введите имя и выберите **Создать ключ API**.\n3. Скопируйте ключ и сохраните его в надежном месте. Полный ключ показывается только один раз.\n\nКаждый ключ действует для одной церкви. Его создатель должен оставаться членом церкви.\n\n## Поиск ID вашей церкви\n\nСкопируйте **ID церкви** со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления. Используйте его как `churchId` в ваших API-запросах.\n\n## Аутентификация\n\nОтправляйте ваш ключ точно так, как скопировали со страницы [API](https://app.withkaleo.com/to/integrations/api) с каждым запросом:\n\n```text\nAuthorization: Bearer YOUR_API_KEY\n```\n\nВ API-песочнице вводите только скопированный ключ. Bearer добавляется автоматически." }, "servers": [ { "url": "https://babel.withkaleo.com", "description": "Производственное API" } ], "tags": [ { "name": "Languages", "description": "Поддерживаемые языки диктора и перевода.", "x-displayName": "Языки" }, { "name": "Devices", "description": "Устройства Kaleo Connect, которые можно мониторить и управлять ими удаленно через API.", "x-displayName": "Устройства" }, { "name": "Streaming", "description": "**Примечание: конечная точка Start streaming может использоваться только для запуска трансляции с устройства Kaleo Connect.** Эта конечная точка не может использоваться для запуска трансляции из веб-браузера. Все остальные конечные точки трансляции управляют как браузером, так и устройствами Kaleo Connect.", "x-displayName": "Трансляция" }, { "name": "Sessions", "description": "История сессий и аналитика зрителей.", "x-displayName": "Сессии" } ], "security": [ { "ApiKeyBearer": [] } ], "paths": { "/v1/church/{churchId}/devices": { "get": { "operationId": "listDevices", "summary": "Список устройств", "tags": [ "Devices" ], "description": "Список устройств Kaleo Connect и их готовность к функциям.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Devices" }, "example": { "devices": [ { "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac", "status": "online", "capabilities": [ { "capability": "audio-source", "status": "ready" }, { "capability": "audio-output", "status": "ready" }, { "capability": "propresenter", "status": "unavailable" } ], "lastSeenAt": null } ] } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICES_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List devices" } }, "/v1/church/{churchId}/devices/{deviceId}": { "get": { "operationId": "getDevice", "summary": "Получить устройство", "tags": [ "Devices" ], "description": "Получить одно устройство Kaleo Connect и его готовность к функциям.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID устройства из `GET /devices`." } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDetails" }, "example": { "device": { "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac", "status": "online", "capabilities": [ { "capability": "audio-source", "status": "ready" }, { "capability": "audio-output", "status": "ready" }, { "capability": "propresenter", "status": "unavailable" } ], "lastSeenAt": null } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Устройство не существует в этой церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICE_NOT_FOUND" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICES_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get device" } }, "/v1/church/{churchId}/streaming": { "get": { "operationId": "getStreaming", "summary": "Получить статус трансляции", "tags": [ "Streaming" ], "description": "Получить текущую сессию и общие настройки церкви. Все поля присутствуют, включая состояние бездействия.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get streaming status" } }, "/v1/church/{churchId}/streaming/start": { "post": { "operationId": "startStreaming", "summary": "Начать трансляцию", "tags": [ "Streaming" ], "description": "Начать трансляцию на устройстве Kaleo Connect с использованием сохранённых настроек. Опциональное тело запроса может выбрать `deviceId` и переопределить настройки для этой сессии. Без `deviceId` Kaleo выбирает аудиоисточник по умолчанию, настроенный на странице [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) (в разделе Интеграции) в вашей панели управления, если доступно несколько аудиоустройств, или единственное доступное аудиоустройство, если оно одно.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Неверный JSON, неподдерживаемые поля или недопустимые значения.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "403": { "description": "План, язык или ограничения использования не позволяют начать трансляцию.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "PLAN_LIMIT" } } } }, "409": { "description": "Конфликт активной сессии, отсутствует аудиоисточник или выбор по умолчанию, или выбранное устройство не готово. Проверьте статус трансляции и готовность устройства; выберите устройство по умолчанию на странице [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) (в разделе Интеграции) в вашей панели управления или предоставьте `deviceId` при необходимости.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "ACTIVE_SESSION" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartStreaming" }, "examples": { "defaultAudioSource": { "summary": "Использовать источник звука по умолчанию", "value": {} }, "explicitDevice": { "summary": "Выберите устройство для этой сессии", "value": { "deviceId": "00000000-0000-4000-8000-000000000002" } } } } }, "description": "Опустите тело запроса или отправьте `{}`, чтобы использовать аудиоисточник по умолчанию и сохранённые настройки. Отправьте `deviceId`, чтобы выбрать другое устройство для этой сессии." }, "x-kaleo-anchor": "Start streaming" } }, "/v1/church/{churchId}/streaming/stop": { "post": { "operationId": "stopStreaming", "summary": "Остановить трансляцию", "tags": [ "Streaming" ], "description": "Остановить текущую потоковую сессию. Тело запроса не требуется.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": false, "sessionId": null, "startedAt": null, "deadlineAt": null, "speakerLanguage": null, "targetLanguages": [], "voice": "male", "visible": true, "publisher": null, "phase": "idle", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Stop streaming" } }, "/v1/church/{churchId}/streaming/voice": { "patch": { "operationId": "changeVoice", "summary": "Изменить голос перевода", "tags": [ "Streaming" ], "description": "Изменить голос перевода во время бездействия или трансляции.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "female", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Неверный JSON, неподдерживаемые поля или недопустимые значения.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "Поток изменился или команда не была подтверждена. Проверьте текущий статус трансляции перед отправкой другой команды.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_CHANGED" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVoice" }, "example": { "voice": "female" } } } }, "x-kaleo-anchor": "Change translation voice" } }, "/v1/church/{churchId}/streaming/visibility": { "patch": { "operationId": "changeVisibility", "summary": "Изменить видимость", "tags": [ "Streaming" ], "description": "Показать или скрыть субтитры во время бездействия или трансляции. Скрытие субтитров не останавливает сессию.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": false, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Неверный JSON, неподдерживаемые поля или недопустимые значения.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVisibility" }, "example": { "visible": false } } } }, "x-kaleo-anchor": "Change visibility" } }, "/v1/church/{churchId}/streaming/captions/clear": { "post": { "operationId": "clearCaptions", "summary": "Очистить субтитры", "tags": [ "Streaming" ], "description": "Очистить текущую ленту субтитров. Тело запроса не требуется.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Clear captions" } }, "/v1/church/{churchId}/streaming/deadline": { "patch": { "operationId": "changeDeadline", "summary": "Изменить время автоостановки", "tags": [ "Streaming" ], "description": "Установить время автоостановки для активной сессии. Возвращает обновлённый статус трансляции.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Неверный JSON, неподдерживаемые поля или недопустимые значения.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`STREAM_OFFLINE` при бездействии; `INVALID_DEADLINE` для времени автоостановки вне допустимого диапазона. Проверьте текущий статус трансляции перед отправкой другой команды.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeDeadline" }, "example": { "deadlineAt": "2026-10-08T16:00:00Z" } } } }, "x-kaleo-anchor": "Change auto-stop deadline" } }, "/v1/church/{churchId}/sessions": { "get": { "operationId": "listSessions", "summary": "Список сессий", "tags": [ "Sessions" ], "description": "Список сессий, начиная с самых новых, с аналитикой зрителей.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Номер страницы, начиная с 1. Значения выше последней страницы возвращают последнюю страницу." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 14 }, "description": "Количество сессий на страницу. Значения выше 100 считаются 100." }, { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Включать сессии, начавшиеся в или после этого времени. Указывайте Z или смещение часового пояса." }, { "name": "startedBefore", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Включать сессии, начавшиеся в или до этого времени. Указывайте Z или смещение часового пояса. Должно быть не раньше `startedAfter`." } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPage" }, "example": { "sessions": [ { "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-04T14:00:00.000Z", "endedAt": "2026-10-04T15:00:00.000Z", "duration": 3600, "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "transcriptAvailable": true, "publicSharingEnabled": false, "analytics": { "sessionId": "00000000-0000-4000-8000-000000000001", "status": "finalized", "viewers": 12, "viewerLanguages": { "en": 8, "fr-FR": 6 } } } ], "total": 1, "page": 1, "pageSize": 14 } } }, "headers": { "Cache-Control": { "description": "Ответы на чтение не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Неверная пагинация с положительными целыми числами или неверный/обратный диапазон временных меток.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_HISTORY_RANGE" } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Сервис истории или аутентификации недоступен. Не пустой результат истории.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_HISTORY_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List sessions" } }, "/v1/church/{churchId}/sessions/{sessionId}": { "get": { "operationId": "getSession", "summary": "Получить сессию", "tags": [ "Sessions" ], "description": "Получить одну сессию и её аналитику зрителей.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "ID сессии из `GET /sessions`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetails" }, "example": { "session": { "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-04T14:00:00.000Z", "endedAt": "2026-10-04T15:00:00.000Z", "duration": 3600, "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "transcriptAvailable": true, "publicSharingEnabled": false, "analytics": { "sessionId": "00000000-0000-4000-8000-000000000001", "status": "finalized", "viewers": 12, "viewerLanguages": { "en": 8, "fr-FR": 6 } } } } } }, "headers": { "Cache-Control": { "description": "Ответы на чтение не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Отсутствует, удалена, неверный ID или сессия принадлежит другой церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_NOT_FOUND" } } } }, "503": { "description": "Сервис истории или аутентификации недоступен.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_HISTORY_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get session" } }, "/v1/church/{churchId}/languages/speaker": { "get": { "operationId": "listSpeakerLanguages", "summary": "Список языков диктора", "tags": [ "Languages" ], "description": "Список поддерживаемых языков диктора. Используйте эти коды в `speakerLanguage`.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Сервис аутентификации временно недоступен.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List speaker languages" } }, "/v1/church/{churchId}/languages/target": { "get": { "operationId": "listTargetLanguages", "summary": "Список целевых языков", "tags": [ "Languages" ], "description": "Список поддерживаемых языков перевода. Используйте эти коды в `targetLanguages`.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Сервис аутентификации временно недоступен.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List target languages" } }, "/v1/church/{churchId}/languages/{code}": { "get": { "operationId": "getLanguage", "summary": "Получить язык", "tags": [ "Languages" ], "description": "Получить имена и эмодзи для одного поддерживаемого кода языка.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Точный код языка, например `en` или `zh-Hans`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageDetails" }, "example": { "language": { "code": "fr", "name": "French (General)", "nativeName": "Français", "emoji": "🇫🇷" } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Неподдерживаемый код языка.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "LANGUAGE_NOT_FOUND" } } } }, "503": { "description": "Сервис аутентификации временно недоступен.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get language" } }, "/v1/church/{churchId}/streaming/deadline/adjust": { "post": { "operationId": "adjustDeadline", "summary": "Корректировать время автоостановки", "tags": [ "Streaming" ], "description": "Добавить или вычесть время автоостановки. Во время бездействия изменить длительность для следующего ручного запуска. Во время трансляции изменить текущий срок. Каждый запрос применяет отдельную корректировку.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "ID вашей церкви. Скопируйте его со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Успешно", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "Ответы не кэшируются.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Неверный JSON, неподдерживаемые поля или недопустимые значения.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Отсутствует или недействительный ключ API, включая истечение срока, отзыв, неправильную церковь или если создатель больше не является членом церкви.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`INVALID_DEADLINE` для живого срока вне допустимого диапазона; `DEADLINE_NOT_SET` когда сессия не имеет срока. `SETTINGS_CHANGED` или `SESSION_ACTIVE` при одновременном изменении настроек бездействия или допуска. Проверьте текущий статус трансляции перед отправкой другой команды.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "Временный сбой сервиса или аутентификации. Согласуйте состояние перед повторной попыткой управления.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustDeadline" }, "example": { "deltaSeconds": 120 } } } }, "x-kaleo-anchor": "Adjust auto-stop time" } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Введите ваш ключ API точно так, как скопировали со страницы [API](https://app.withkaleo.com/to/integrations/api) (в разделе Интеграции) в вашей панели управления. Bearer добавляется автоматически. Ключ действует для одной церкви, пока его создатель остаётся членом." } }, "schemas": { "Device": { "type": "object", "properties": { "id": { "type": "string", "description": "ID устройства. Передавайте это значение как `deviceId` в запросах." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "offline", "online", "maintenance" ], "description": "Состояние подключения. Офлайн после 90 секунд без связи; maintenance означает временную недоступность." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceCapability" }, "description": "Готовность каждой функции на этом устройстве." }, "lastSeenAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Последний контакт с Kaleo; `null`, если неизвестно." } }, "required": [ "id", "name", "status", "capabilities", "lastSeenAt" ], "additionalProperties": false }, "DeviceCapability": { "type": "object", "properties": { "capability": { "type": "string", "enum": [ "audio-source", "audio-output", "propresenter" ], "description": "Локальная функция: захват аудио, воспроизведение переведённой речи или ввод слайдов ProPresenter." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "offline" ], "description": "Готовность этой функции к использованию." } }, "required": [ "capability", "status" ], "additionalProperties": false }, "Devices": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } }, "required": [ "devices" ], "additionalProperties": false }, "DeviceDetails": { "type": "object", "properties": { "device": { "$ref": "#/components/schemas/Device" } }, "required": [ "device" ], "additionalProperties": false }, "ProPresenterSelection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "default" ], "description": "Использовать устройство ProPresenter по умолчанию для церкви." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ], "description": "Не использовать ProPresenter для этой сессии." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "device" ], "description": "Использовать устройство, указанное в `deviceId`." }, "deviceId": { "type": "string", "description": "ID устройства источника ProPresenter из `GET /devices`. Может отличаться от аудиоисточника." } }, "required": [ "mode", "deviceId" ], "additionalProperties": false } ], "description": "Выберите источник ProPresenter для этой сессии. Настройте его подключение в Connect." }, "StartStreaming": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Опциональный ID устройства аудиоисточника из `GET /devices`. Переопределяет аудиоисточник по умолчанию церкви для этой сессии. Если не указан, используется сохранённый аудиоисточник по умолчанию или единственное аудиоустройство; при наличии нескольких устройств без выбора по умолчанию требуется выбор. Выбранное устройство должно быть готово." }, "overrides": { "type": "object", "properties": { "speakerLanguage": { "type": "string", "description": "Код из `GET /languages/speaker`. Используйте `\"mul\"` для многоязычного режима." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Коды из `GET /languages/target`. Используйте `[\"ALL\"]` для всех поддерживаемых целей в пределах вашего плана." }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "Время до автоматической остановки в секундах." }, "proPresenter": { "$ref": "#/components/schemas/ProPresenterSelection" } }, "required": [], "additionalProperties": false, "description": "Настройки только для этой сессии. Пропущенные поля используют сохранённые значения по умолчанию." } }, "required": [], "additionalProperties": false }, "ChangeVoice": { "type": "object", "properties": { "voice": { "type": "string", "enum": [ "male", "female" ], "description": "Голос перевода. Может изменяться во время бездействия или трансляции." } }, "required": [ "voice" ], "additionalProperties": false }, "ChangeVisibility": { "type": "object", "properties": { "visible": { "type": "boolean", "description": "`true` показывает субтитры; `false` скрывает их при продолжающейся трансляции." } }, "required": [ "visible" ], "additionalProperties": false }, "ChangeDeadline": { "type": "object", "properties": { "deadlineAt": { "type": "string", "format": "date-time", "description": "Будущее время автоостановки с Z или смещением часового пояса. Не позже шести часов после `startedAt`." } }, "required": [ "deadlineAt" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" } }, "required": [ "success", "error" ] }, "Analytics": { "type": "object", "properties": { "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "pending", "finalized" ], "description": "`live`: предварительные подсчёты; `pending`: ожидание окончательных подсчётов; `finalized`: сохранённые подсчёты." }, "viewers": { "type": "integer", "minimum": 0, "nullable": true, "description": "Уникальные идентификаторы зрителей сессии, не текущие зрители. `null`, если недоступно; 0 означает отсутствие зрителей." }, "viewerLanguages": { "type": "object", "nullable": true, "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Аналитика зрителей по кодам языков. Один зритель может появляться в нескольких языках. `null`, если недоступно." } }, "required": [ "sessionId", "status", "viewers", "viewerLanguages" ] }, "HistorySession": { "type": "object", "properties": { "sessionId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Время окончания сессии; `null`, если не завершена или недоступна." }, "duration": { "type": "integer", "nullable": true, "description": "Записанная длительность сессии в секундах; `null`, если не завершена или недоступна." }, "speakerLanguage": { "type": "string", "nullable": true, "description": "Код языка диктора; `null`, если не записан." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Коды языков перевода, или `[\"ALL\"]`." }, "transcriptAvailable": { "type": "boolean", "description": "`true`, когда сохранённая расшифровка готова. Не даёт публичного доступа или URL для скачивания." }, "publicSharingEnabled": { "type": "boolean", "description": "`true`, когда публичный доступ включён для завершённой сессии." }, "analytics": { "$ref": "#/components/schemas/Analytics" } }, "required": [ "sessionId", "startedAt", "endedAt", "duration", "speakerLanguage", "targetLanguages", "transcriptAvailable", "publicSharingEnabled", "analytics" ] }, "HistoryPage": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/HistorySession" } }, "total": { "type": "integer", "minimum": 0, "description": "Общее количество сессий, соответствующих фильтрам, по всем страницам." }, "page": { "type": "integer", "minimum": 1, "description": "Возвращённая страница; может быть меньше запрошенной." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Максимальное количество сессий на страницу, ограничено 100." } }, "required": [ "sessions", "total", "page", "pageSize" ] }, "SessionDetails": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/HistorySession" } }, "required": [ "session" ] }, "Language": { "type": "object", "properties": { "code": { "type": "string", "description": "Используйте этот точный код в языковых полях." }, "name": { "type": "string", "description": "Название на английском языке." }, "nativeName": { "type": "string", "description": "Название на собственном языке; английское, если недоступно." }, "emoji": { "type": "string", "description": "Отображаемый эмодзи для этого языка." } }, "required": [ "code", "name", "nativeName", "emoji" ], "additionalProperties": false }, "Languages": { "type": "object", "properties": { "languages": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } }, "required": [ "languages" ], "additionalProperties": false }, "LanguageDetails": { "type": "object", "properties": { "language": { "$ref": "#/components/schemas/Language" } }, "required": [ "language" ], "additionalProperties": false }, "StreamingStatus": { "type": "object", "properties": { "streaming": { "type": "boolean", "description": "`true` во время активной сессии, включая запуск, переподключения и завершение. Не подтверждает поступление аудио." }, "sessionId": { "type": "string", "nullable": true, "description": "Текущий ID сессии; `null` во время бездействия." }, "startedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Время начала текущей сессии; `null` во время бездействия." }, "deadlineAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Время автоматической остановки; `null` во время бездействия или если срок не установлен." }, "speakerLanguage": { "type": "string", "nullable": true, "description": "Код языка диктора; `null` во время бездействия." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Коды языков перевода; пусто во время бездействия." }, "voice": { "type": "string", "enum": [ "male", "female", null ], "nullable": false, "description": "Голос перевода, включая состояние бездействия." }, "visible": { "type": "boolean", "description": "`true` показывает субтитры; `false` скрывает их. Также применяется во время бездействия." }, "publisher": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "connect" ] }, "id": { "type": "string", "description": "ID устройства, когда `kind` равно `connect`; ID браузера-публикатора, когда `kind` равно `browser`." }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ], "additionalProperties": false, "nullable": true, "description": "Устройство Kaleo Connect или браузер, отправляющий аудио; `null` во время бездействия." }, "phase": { "type": "string", "enum": [ "idle", "starting", "streaming", "reconnecting", "ending" ], "description": "Этап сессии; idle означает отсутствие активной сессии." }, "streamSettings": { "type": "object", "description": "Настройки по умолчанию церкви для следующего ручного запуска. Активная сессия не изменяет эти значения.", "required": [ "revision", "settings" ], "properties": { "revision": { "type": "integer", "minimum": 0, "description": "Увеличивается при изменении этих настроек по умолчанию." }, "settings": { "type": "object", "required": [ "speakerLanguage", "targetLanguages", "duration" ], "properties": { "speakerLanguage": { "type": "string", "description": "Код языка диктора по умолчанию." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Коды языков перевода по умолчанию; `[\"ALL\"]` выбирает все поддерживаемые цели." }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "Время до автоматической остановки в секундах." } } } } } }, "required": [ "streaming", "phase", "sessionId", "startedAt", "deadlineAt", "speakerLanguage", "targetLanguages", "voice", "visible", "publisher", "streamSettings" ], "additionalProperties": false, "description": "Текущая сессия и общие настройки церкви. Все поля присутствуют, включая состояние бездействия." }, "AdjustDeadline": { "type": "object", "additionalProperties": false, "required": [ "deltaSeconds" ], "properties": { "deltaSeconds": { "type": "integer", "minimum": -21600, "maximum": 21600, "description": "Секунды для добавления к длительности бездействия или текущему сроку; отрицательные значения вычитают. Не может быть 0. Длительность бездействия: 60–21600 секунд. Живой срок: будущее, в пределах шести часов от `startedAt`.", "not": { "enum": [ 0 ] } } } } } } }