{ "openapi": "3.0.3", "info": { "title": "Kaleo API", "version": "2026-10-08", "description": "Kaleo AI provides a web API to control your streaming sessions, retrieve viewer analytics, and monitor Kaleo Connect devices. You can use our API to integrate into your custom AVL controls and workflows as needed.\n\nTo get started, follow the instructions below to get an API key, find your church ID, and authenticate your requests.\n\n## Get an API key\n\n1. Go to the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.\n2. Enter a name and select **Create API key**.\n3. Copy the key and store it securely. The full key is shown only once.\n\nEach key works for one church. Its creator must remain a church member.\n\n## Find your church ID\n\nCopy the **Church ID** from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard. Use it as `churchId` in your API requests.\n\n## Authentication\n\nSend your key exactly as copied from the [API](https://app.withkaleo.com/to/integrations/api) page with every request:\n\n```text\nAuthorization: Bearer YOUR_API_KEY\n```\n\nIn the API playground, enter only your copied key. Bearer is added automatically." }, "servers": [ { "url": "https://babel.withkaleo.com", "description": "Production API" } ], "tags": [ { "name": "Languages", "description": "Supported speaker and translation languages." }, { "name": "Devices", "description": "Kaleo Connect devices that can be monitored and remote-controlled via API." }, { "name": "Streaming", "description": "**Note: the Start streaming endpoint can only be used to start streaming from a Kaleo Connect device.** This endpoint cannot be used to start streaming from a web browser. All other streaming endpoints control both browser and Kaleo Connect devices." }, { "name": "Sessions", "description": "Session history and viewer analytics." } ], "security": [ { "ApiKeyBearer": [] } ], "paths": { "/v1/church/{churchId}/devices": { "get": { "operationId": "listDevices", "summary": "List devices", "tags": [ "Devices" ], "description": "List Kaleo Connect devices and their feature readiness.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICES_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/devices/{deviceId}": { "get": { "operationId": "getDevice", "summary": "Get device", "tags": [ "Devices" ], "description": "Read one Kaleo Connect device and its feature readiness.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Device ID from `GET /devices`." } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Device does not exist in this church.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICE_NOT_FOUND" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICES_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/streaming": { "get": { "operationId": "getStreaming", "summary": "Get streaming status", "tags": [ "Streaming" ], "description": "Read the current session and shared church settings. All fields are present, including while idle.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/streaming/start": { "post": { "operationId": "startStreaming", "summary": "Start streaming", "tags": [ "Streaming" ], "description": "Start streaming on a Kaleo Connect device using saved settings. The optional body can select a `deviceId` and override settings for this session. Without `deviceId`, Kaleo picks the default audio source configured on the [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) page (under Integrations) in your dashboard if there are multiple audio-capable devices available, or the only available audio source device if just one is available.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Malformed JSON, unsupported fields, or invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "403": { "description": "Plan, language, or usage limits prevent this start.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "PLAN_LIMIT" } } } }, "409": { "description": "Active-session conflict, missing audio source or default selection, or selected device not ready. Read streaming status and device readiness; choose a default on the [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) page (under Integrations) in your dashboard or provide `deviceId` when needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "ACTIVE_SESSION" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "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": "Use the default audio source", "value": {} }, "explicitDevice": { "summary": "Choose a device for this session", "value": { "deviceId": "00000000-0000-4000-8000-000000000002" } } } } }, "description": "Omit the body or send `{}` to use the default audio source and saved settings. Send `deviceId` to choose another device for this session." } } }, "/v1/church/{churchId}/streaming/stop": { "post": { "operationId": "stopStreaming", "summary": "Stop streaming", "tags": [ "Streaming" ], "description": "Stop the current streaming session. No request body is needed.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/streaming/voice": { "patch": { "operationId": "changeVoice", "summary": "Change translation voice", "tags": [ "Streaming" ], "description": "Change the translation voice while idle or streaming.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Malformed JSON, unsupported fields, or invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "The stream changed or the command could not be confirmed. Read current streaming status before sending another command.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_CHANGED" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "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" } } } } } }, "/v1/church/{churchId}/streaming/visibility": { "patch": { "operationId": "changeVisibility", "summary": "Change visibility", "tags": [ "Streaming" ], "description": "Show or hide captions while idle or streaming. Hiding captions does not stop the session.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Malformed JSON, unsupported fields, or invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "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 } } } } } }, "/v1/church/{churchId}/streaming/captions/clear": { "post": { "operationId": "clearCaptions", "summary": "Clear captions", "tags": [ "Streaming" ], "description": "Clear the current caption feed. No request body is needed.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/streaming/deadline": { "patch": { "operationId": "changeDeadline", "summary": "Change auto-stop deadline", "tags": [ "Streaming" ], "description": "Set the auto-stop time for an active session. Returns the updated streaming status.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Malformed JSON, unsupported fields, or invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`STREAM_OFFLINE` when idle; `INVALID_DEADLINE` for a deadline outside the permitted window. Read current streaming status before sending another command.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "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" } } } } } }, "/v1/church/{churchId}/sessions": { "get": { "operationId": "listSessions", "summary": "List sessions", "tags": [ "Sessions" ], "description": "List sessions, newest first, with viewer analytics.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number, starting at 1. Values above the last page return the last page." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 14 }, "description": "Sessions per page. Values above 100 use 100." }, { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Include sessions started at or after this time. Include Z or a timezone offset." }, { "name": "startedBefore", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Include sessions started at or before this time. Include Z or a timezone offset. Must be at or after `startedAfter`." } ], "responses": { "200": { "description": "Success", "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": "Read responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Invalid positive-integer pagination or invalid/reversed timestamp range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_HISTORY_RANGE" } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a church member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "History or authentication service unavailable. Not an empty history result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_HISTORY_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/sessions/{sessionId}": { "get": { "operationId": "getSession", "summary": "Get session", "tags": [ "Sessions" ], "description": "Read one session and its viewer analytics.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "Session ID from `GET /sessions`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Read responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a church member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Missing, removed, invalid-ID, or differently owned session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_NOT_FOUND" } } } }, "503": { "description": "History or authentication service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_HISTORY_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/languages/speaker": { "get": { "operationId": "listSpeakerLanguages", "summary": "List speaker languages", "tags": [ "Languages" ], "description": "List supported speaker languages. Use these codes in `speakerLanguage`.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Authentication service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/languages/target": { "get": { "operationId": "listTargetLanguages", "summary": "List target languages", "tags": [ "Languages" ], "description": "List supported translation languages. Use these codes in `targetLanguages`.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Authentication service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/languages/{code}": { "get": { "operationId": "getLanguage", "summary": "Get language", "tags": [ "Languages" ], "description": "Read the names and emoji for one supported language code.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Exact language code, such as `en` or `zh-Hans`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageDetails" }, "example": { "language": { "code": "fr", "name": "French (General)", "nativeName": "Français", "emoji": "🇫🇷" } } } }, "headers": { "Cache-Control": { "description": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Unsupported language code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "LANGUAGE_NOT_FOUND" } } } }, "503": { "description": "Authentication service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } } } }, "/v1/church/{churchId}/streaming/deadline/adjust": { "post": { "operationId": "adjustDeadline", "summary": "Adjust auto-stop time", "tags": [ "Streaming" ], "description": "Add or subtract auto-stop time. While idle, change the duration for the next manual start. While streaming, change the current deadline. Each request applies a separate adjustment.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "Your church ID. Copy it from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "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": "Responses are not cached.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Malformed JSON, unsupported fields, or invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Missing or invalid API key, including expiry, revocation, wrong church, or owner no longer a member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`INVALID_DEADLINE` for a live deadline outside the permitted window; `DEADLINE_NOT_SET` when the session has no deadline. `SETTINGS_CHANGED` or `SESSION_ACTIVE` when idle settings or admission changed concurrently. Read current streaming status before sending another command.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "Temporary service or authentication failure. Reconcile state before retrying a control request.", "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 } } } } } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Enter your API key exactly as copied from the [API](https://app.withkaleo.com/to/integrations/api) page (under Integrations) in your dashboard. Bearer is added automatically. It works for one church while its creator remains a member." } }, "schemas": { "Device": { "type": "object", "properties": { "id": { "type": "string", "description": "Device ID. Pass this value as `deviceId` in requests." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "offline", "online", "maintenance" ], "description": "Connection state. Offline after 90 seconds without contact; maintenance means temporarily unavailable." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceCapability" }, "description": "Readiness of each feature on this device." }, "lastSeenAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last contact with Kaleo; `null` if unknown." } }, "required": [ "id", "name", "status", "capabilities", "lastSeenAt" ], "additionalProperties": false }, "DeviceCapability": { "type": "object", "properties": { "capability": { "type": "string", "enum": [ "audio-source", "audio-output", "propresenter" ], "description": "Local feature: audio capture, translated speech playback, or ProPresenter slide input." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "offline" ], "description": "Whether this feature is ready to use." } }, "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": "Use the church's default ProPresenter device." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ], "description": "Do not use ProPresenter for this session." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "device" ], "description": "Use the device specified by `deviceId`." }, "deviceId": { "type": "string", "description": "Device ID of the ProPresenter source, from `GET /devices`. May differ from the audio source." } }, "required": [ "mode", "deviceId" ], "additionalProperties": false } ], "description": "Choose the ProPresenter source for this session. Configure its connection in Connect." }, "StartStreaming": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Optional audio source device ID from `GET /devices`. Overrides the church default for this session. If omitted, use the saved default audio source or the sole audio-source-capable paired device; multiple devices without a default require selection. The selected device must still be ready." }, "overrides": { "type": "object", "properties": { "speakerLanguage": { "type": "string", "description": "Code from `GET /languages/speaker`. Use `\"mul\"` for Multilingual mode." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Codes from `GET /languages/target`. Use `[\"ALL\"]` for all supported targets, within your plan limit." }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "Time until automatic stop, in seconds." }, "proPresenter": { "$ref": "#/components/schemas/ProPresenterSelection" } }, "required": [], "additionalProperties": false, "description": "Settings for this session only. Omitted fields use saved defaults." } }, "required": [], "additionalProperties": false }, "ChangeVoice": { "type": "object", "properties": { "voice": { "type": "string", "enum": [ "male", "female" ], "description": "Translation voice. Can change while idle or streaming." } }, "required": [ "voice" ], "additionalProperties": false }, "ChangeVisibility": { "type": "object", "properties": { "visible": { "type": "boolean", "description": "`true` shows captions; `false` hides them while streaming continues." } }, "required": [ "visible" ], "additionalProperties": false }, "ChangeDeadline": { "type": "object", "properties": { "deadlineAt": { "type": "string", "format": "date-time", "description": "Future auto-stop time with Z or a timezone offset. No later than six hours after `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`: provisional counts; `pending`: awaiting final counts; `finalized`: saved counts." }, "viewers": { "type": "integer", "minimum": 0, "nullable": true, "description": "Unique viewer identities for the session, not current viewers. `null` if unavailable; 0 means no viewers." }, "viewerLanguages": { "type": "object", "nullable": true, "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Viewer analytics by language code. A viewer may appear in several languages. `null` if unavailable." } }, "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": "Session end time; `null` if unfinished or unavailable." }, "duration": { "type": "integer", "nullable": true, "description": "Recorded session length in seconds; `null` if unfinished or unavailable." }, "speakerLanguage": { "type": "string", "nullable": true, "description": "Speaker language code; `null` if not recorded." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Recorded translation language codes, or `[\"ALL\"]`." }, "transcriptAvailable": { "type": "boolean", "description": "`true` when the saved transcript is ready. Does not grant public access or a download URL." }, "publicSharingEnabled": { "type": "boolean", "description": "`true` when public sharing is enabled for the completed session." }, "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": "Total sessions that match the filters, across all pages." }, "page": { "type": "integer", "minimum": 1, "description": "Page returned; may be lower than requested." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum sessions per page, capped at 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": "Use this exact code in language fields." }, "name": { "type": "string", "description": "English display name." }, "nativeName": { "type": "string", "description": "Name in its own language; English if unavailable." }, "emoji": { "type": "string", "description": "Display emoji for this language." } }, "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` during an active session, including startup, reconnects, and shutdown. Does not confirm audio is arriving." }, "sessionId": { "type": "string", "nullable": true, "description": "Current session ID; `null` while idle." }, "startedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Current session start time; `null` while idle." }, "deadlineAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Automatic stop time; `null` while idle or if no deadline is recorded." }, "speakerLanguage": { "type": "string", "nullable": true, "description": "Current speaker language code; `null` while idle." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Current translation language codes; empty while idle." }, "voice": { "type": "string", "enum": [ "male", "female", null ], "nullable": false, "description": "Translation voice, including while idle." }, "visible": { "type": "boolean", "description": "`true` shows captions; `false` hides them. Also applies while idle." }, "publisher": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "connect" ] }, "id": { "type": "string", "description": "Device ID when `kind` is `connect`; browser publisher ID when `kind` is `browser`." }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ], "additionalProperties": false, "nullable": true, "description": "Kaleo Connect device or browser that sends audio; `null` while idle." }, "phase": { "type": "string", "enum": [ "idle", "starting", "streaming", "reconnecting", "ending" ], "description": "Session stage; idle means no session is active." }, "streamSettings": { "type": "object", "description": "Church defaults for the next manual start. Active session overrides do not change these values.", "required": [ "revision", "settings" ], "properties": { "revision": { "type": "integer", "minimum": 0, "description": "Increases when these defaults change." }, "settings": { "type": "object", "required": [ "speakerLanguage", "targetLanguages", "duration" ], "properties": { "speakerLanguage": { "type": "string", "description": "Default speaker language code." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Default translation language codes; `[\"ALL\"]` selects all supported targets." }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "Time until automatic stop, in seconds." } } } } } }, "required": [ "streaming", "phase", "sessionId", "startedAt", "deadlineAt", "speakerLanguage", "targetLanguages", "voice", "visible", "publisher", "streamSettings" ], "additionalProperties": false, "description": "Current session and shared church settings. All fields are present, including while idle." }, "AdjustDeadline": { "type": "object", "additionalProperties": false, "required": [ "deltaSeconds" ], "properties": { "deltaSeconds": { "type": "integer", "minimum": -21600, "maximum": 21600, "description": "Seconds to add to the idle duration or current deadline; negative values subtract. Cannot be 0. Idle duration: 60–21600 seconds. Live deadline: future, within six hours of `startedAt`.", "not": { "enum": [ 0 ] } } } } } } }