{ "openapi": "3.0.3", "info": { "title": "API Kaleo", "version": "2026-10-08", "description": "Kaleo AI fornece uma API web para controlar suas sessões de streaming, recuperar análises de espectadores e monitorar dispositivos Kaleo Connect. Você pode usar nossa API para integrar em seus controles AVL personalizados e fluxos de trabalho conforme necessário.\n\nPara começar, siga as instruções abaixo para obter uma chave de API, encontrar o ID da sua igreja e autenticar suas solicitações.\n\n## Obter uma chave de API\n\n1. Vá para a página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.\n2. Insira um nome e selecione **Criar chave de API**.\n3. Copie a chave e armazene-a com segurança. A chave completa é exibida apenas uma vez.\n\nCada chave funciona para uma igreja. Seu criador deve permanecer membro da igreja.\n\n## Encontrar o ID da sua igreja\n\nCopie o **ID da Igreja** da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel. Use-o como `churchId` em suas solicitações de API.\n\n## Autenticação\n\nEnvie sua chave exatamente como copiada da página [API](https://app.withkaleo.com/to/integrations/api) com cada solicitação:\n\n```text\nAuthorization: Bearer YOUR_API_KEY\n```\n\nNo playground da API, insira apenas sua chave copiada. Bearer é adicionado automaticamente." }, "servers": [ { "url": "https://babel.withkaleo.com", "description": "API de Produção" } ], "tags": [ { "name": "Languages", "description": "Idiomas suportados para locutores e tradução.", "x-displayName": "Idiomas" }, { "name": "Devices", "description": "Dispositivos Kaleo Connect que podem ser monitorados e controlados remotamente via API.", "x-displayName": "Dispositivos" }, { "name": "Streaming", "description": "**Nota: o endpoint Iniciar streaming só pode ser usado para iniciar streaming a partir de um dispositivo Kaleo Connect.** Este endpoint não pode ser usado para iniciar streaming a partir de um navegador web. Todos os outros endpoints de streaming controlam tanto navegadores quanto dispositivos Kaleo Connect.", "x-displayName": "Streaming" }, { "name": "Sessions", "description": "Histórico de sessões e análises de espectadores.", "x-displayName": "Sessões" } ], "security": [ { "ApiKeyBearer": [] } ], "paths": { "/v1/church/{churchId}/devices": { "get": { "operationId": "listDevices", "summary": "Listar dispositivos", "tags": [ "Devices" ], "description": "Liste dispositivos Kaleo Connect e sua prontidão de recursos.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Obter dispositivo", "tags": [ "Devices" ], "description": "Leia um dispositivo Kaleo Connect e sua prontidão de recursos.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do dispositivo de `GET /devices`." } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Dispositivo não existe nesta igreja.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICE_NOT_FOUND" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Obter status de streaming", "tags": [ "Streaming" ], "description": "Leia a sessão atual e as configurações compartilhadas da igreja. Todos os campos estão presentes, inclusive quando ocioso.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Iniciar streaming", "tags": [ "Streaming" ], "description": "Inicie o streaming em um dispositivo Kaleo Connect usando configurações salvas. O corpo opcional pode selecionar um `deviceId` e substituir configurações para esta sessão. Sem `deviceId`, Kaleo escolhe a fonte de áudio padrão configurada na página [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) (em Integrações) no seu painel se houver vários dispositivos com capacidade de áudio disponíveis, ou o único dispositivo fonte de áudio disponível se houver apenas um.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "JSON malformado, campos não suportados ou valores inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "403": { "description": "Limites de plano, idioma ou uso impedem este início.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "PLAN_LIMIT" } } } }, "409": { "description": "Conflito de sessão ativa, falta de fonte de áudio ou seleção padrão, ou dispositivo selecionado não está pronto. Leia o status de streaming e a prontidão do dispositivo; escolha um padrão na página [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) (em Integrações) no seu painel ou forneça `deviceId` quando necessário.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "ACTIVE_SESSION" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Usar a fonte de áudio padrão", "value": {} }, "explicitDevice": { "summary": "Escolha um dispositivo para esta sessão", "value": { "deviceId": "00000000-0000-4000-8000-000000000002" } } } } }, "description": "Omitir o corpo ou enviar `{}` para usar a fonte de áudio padrão e configurações salvas. Enviar `deviceId` para escolher outro dispositivo para esta sessão." }, "x-kaleo-anchor": "Start streaming" } }, "/v1/church/{churchId}/streaming/stop": { "post": { "operationId": "stopStreaming", "summary": "Parar streaming", "tags": [ "Streaming" ], "description": "Pare a sessão de streaming atual. Nenhum corpo de solicitação é necessário.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Alterar voz da tradução", "tags": [ "Streaming" ], "description": "Altere a voz da tradução enquanto estiver ocioso ou transmitindo.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "JSON malformado, campos não suportados ou valores inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "O stream mudou ou o comando não pôde ser confirmado. Leia o status atual do streaming antes de enviar outro comando.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_CHANGED" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Alterar visibilidade", "tags": [ "Streaming" ], "description": "Mostrar ou ocultar legendas enquanto estiver ocioso ou transmitindo. Ocultar legendas não interrompe a sessão.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "JSON malformado, campos não suportados ou valores inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Limpar legendas", "tags": [ "Streaming" ], "description": "Limpe o feed de legendas atual. Nenhum corpo de solicitação é necessário.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Alterar prazo de parada automática", "tags": [ "Streaming" ], "description": "Defina o tempo de parada automática para uma sessão ativa. Retorna o status atualizado do streaming.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "JSON malformado, campos não suportados ou valores inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`STREAM_OFFLINE` quando ocioso; `INVALID_DEADLINE` para um prazo fora da janela permitida. Leia o status atual do streaming antes de enviar outro comando.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Listar sessões", "tags": [ "Sessions" ], "description": "Liste sessões, da mais recente para a mais antiga, com análises de espectadores.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Número da página, começando em 1. Valores acima da última página retornam a última página." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 14 }, "description": "Sessões por página. Valores acima de 100 usam 100." }, { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclua sessões iniciadas a partir desta hora. Inclua Z ou um deslocamento de fuso horário." }, { "name": "startedBefore", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclua sessões iniciadas até esta hora. Inclua Z ou um deslocamento de fuso horário. Deve ser igual ou posterior a `startedAfter`." } ], "responses": { "200": { "description": "Sucesso", "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": "Respostas de leitura não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "Paginação inválida de inteiro positivo ou intervalo de timestamp inválido/invertido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_HISTORY_RANGE" } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro da igreja.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Serviço de histórico ou autenticação indisponível. Não é um resultado vazio de histórico.", "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": "Obter sessão", "tags": [ "Sessions" ], "description": "Leia uma sessão e suas análises de espectadores.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "ID da sessão de `GET /sessions`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "Respostas de leitura não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro da igreja.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Sessão ausente, removida, ID inválido ou de propriedade diferente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_NOT_FOUND" } } } }, "503": { "description": "Serviço de histórico ou autenticação indisponível.", "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": "Listar idiomas de locutor", "tags": [ "Languages" ], "description": "Liste idiomas de locutor suportados. Use esses códigos em `speakerLanguage`.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Serviço de autenticação temporariamente indisponível.", "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": "Listar idiomas de destino", "tags": [ "Languages" ], "description": "Liste idiomas de tradução suportados. Use esses códigos em `targetLanguages`.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "Serviço de autenticação temporariamente indisponível.", "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": "Obter idioma", "tags": [ "Languages" ], "description": "Leia os nomes e emoji para um código de idioma suportado.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Código exato do idioma, como `en` ou `zh-Hans`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageDetails" }, "example": { "language": { "code": "fr", "name": "French (General)", "nativeName": "Français", "emoji": "🇫🇷" } } } }, "headers": { "Cache-Control": { "description": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "Código de idioma não suportado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "LANGUAGE_NOT_FOUND" } } } }, "503": { "description": "Serviço de autenticação temporariamente indisponível.", "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": "Ajustar tempo de parada automática", "tags": [ "Streaming" ], "description": "Adicione ou subtraia tempo de parada automática. Enquanto ocioso, altere a duração para o próximo início manual. Enquanto transmitindo, altere o prazo atual. Cada solicitação aplica um ajuste separado.", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "O ID da sua igreja. Copie-o da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "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": "As respostas não são armazenadas em cache.", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "JSON malformado, campos não suportados ou valores inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "Chave de API ausente ou inválida, incluindo expiração, revogação, igreja errada ou criador não é mais membro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`INVALID_DEADLINE` para um prazo ao vivo fora da janela permitida; `DEADLINE_NOT_SET` quando a sessão não tem prazo. `SETTINGS_CHANGED` ou `SESSION_ACTIVE` quando configurações ociosas ou admissão mudaram simultaneamente. Leia o status atual do streaming antes de enviar outro comando.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "Falha temporária de serviço ou autenticação. Reconcile o estado antes de tentar novamente uma solicitação de controle.", "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": "Digite sua chave de API exatamente como copiada da página [API](https://app.withkaleo.com/to/integrations/api) (em Integrações) no seu painel. Bearer é adicionado automaticamente. Funciona para uma igreja enquanto seu criador permanecer membro." } }, "schemas": { "Device": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do dispositivo. Passe este valor como `deviceId` nas solicitações." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "offline", "online", "maintenance" ], "description": "Estado da conexão. Offline após 90 segundos sem contato; manutenção significa temporariamente indisponível." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceCapability" }, "description": "Prontidão de cada recurso neste dispositivo." }, "lastSeenAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Último contato com Kaleo; `null` se desconhecido." } }, "required": [ "id", "name", "status", "capabilities", "lastSeenAt" ], "additionalProperties": false }, "DeviceCapability": { "type": "object", "properties": { "capability": { "type": "string", "enum": [ "audio-source", "audio-output", "propresenter" ], "description": "Recurso local: captura de áudio, reprodução de fala traduzida ou entrada de slide ProPresenter." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "offline" ], "description": "Se este recurso está pronto para uso." } }, "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 o dispositivo ProPresenter padrão da igreja." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ], "description": "Não use ProPresenter para esta sessão." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "device" ], "description": "Use o dispositivo especificado por `deviceId`." }, "deviceId": { "type": "string", "description": "ID do dispositivo da fonte ProPresenter, de `GET /devices`. Pode ser diferente da fonte de áudio." } }, "required": [ "mode", "deviceId" ], "additionalProperties": false } ], "description": "Escolha a fonte ProPresenter para esta sessão. Configure sua conexão no Connect." }, "StartStreaming": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "ID opcional do dispositivo fonte de áudio de `GET /devices`. Substitui o padrão da igreja para esta sessão. Se omitido, use a fonte de áudio padrão salva ou o único dispositivo pareado com capacidade de áudio; múltiplos dispositivos sem padrão requerem seleção. O dispositivo selecionado deve estar pronto." }, "overrides": { "type": "object", "properties": { "speakerLanguage": { "type": "string", "description": "Código de `GET /languages/speaker`. Use `\"mul\"` para modo multilíngue." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Códigos de `GET /languages/target`. Use `[\"ALL\"]` para todos os alvos suportados, dentro do limite do seu plano." }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "Tempo até a parada automática, em segundos." }, "proPresenter": { "$ref": "#/components/schemas/ProPresenterSelection" } }, "required": [], "additionalProperties": false, "description": "Configurações apenas para esta sessão. Campos omitidos usam padrões salvos." } }, "required": [], "additionalProperties": false }, "ChangeVoice": { "type": "object", "properties": { "voice": { "type": "string", "enum": [ "male", "female" ], "description": "Voz da tradução. Pode ser alterada enquanto ocioso ou transmitindo." } }, "required": [ "voice" ], "additionalProperties": false }, "ChangeVisibility": { "type": "object", "properties": { "visible": { "type": "boolean", "description": "`true` mostra legendas; `false` as oculta enquanto o streaming continua." } }, "required": [ "visible" ], "additionalProperties": false }, "ChangeDeadline": { "type": "object", "properties": { "deadlineAt": { "type": "string", "format": "date-time", "description": "Hora futura de parada automática com Z ou deslocamento de fuso horário. Não mais tarde que seis horas após `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`: contagens provisórias; `pending`: aguardando contagens finais; `finalized`: contagens salvas." }, "viewers": { "type": "integer", "minimum": 0, "nullable": true, "description": "Identidades únicas de espectadores para a sessão, não espectadores atuais. `null` se indisponível; 0 significa sem espectadores." }, "viewerLanguages": { "type": "object", "nullable": true, "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Análises de espectadores por código de idioma. Um espectador pode aparecer em vários idiomas. `null` se indisponível." } }, "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": "Hora de término da sessão; `null` se não finalizada ou indisponível." }, "duration": { "type": "integer", "nullable": true, "description": "Duração registrada da sessão em segundos; `null` se não finalizada ou indisponível." }, "speakerLanguage": { "type": "string", "nullable": true, "description": "Código do idioma do locutor; `null` se não registrado." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Códigos dos idiomas de tradução registrados, ou `[\"ALL\"]`." }, "transcriptAvailable": { "type": "boolean", "description": "`true` quando a transcrição salva está pronta. Não concede acesso público ou URL de download." }, "publicSharingEnabled": { "type": "boolean", "description": "`true` quando o compartilhamento público está habilitado para a sessão concluída." }, "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 de sessões que correspondem aos filtros, em todas as páginas." }, "page": { "type": "integer", "minimum": 1, "description": "Página retornada; pode ser menor que a solicitada." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Máximo de sessões por página, limitado a 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 este código exato nos campos de idioma." }, "name": { "type": "string", "description": "Nome exibido em inglês." }, "nativeName": { "type": "string", "description": "Nome no próprio idioma; inglês se indisponível." }, "emoji": { "type": "string", "description": "Emoji exibido para este idioma." } }, "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` durante uma sessão ativa, incluindo inicialização, reconexões e desligamento. Não confirma que o áudio está chegando." }, "sessionId": { "type": "string", "nullable": true, "description": "ID da sessão atual; `null` enquanto ocioso." }, "startedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Hora de início da sessão atual; `null` enquanto ocioso." }, "deadlineAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Hora de parada automática; `null` enquanto ocioso ou se nenhum prazo está registrado." }, "speakerLanguage": { "type": "string", "nullable": true, "description": "Código do idioma do locutor atual; `null` enquanto ocioso." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Códigos dos idiomas de tradução atuais; vazio enquanto ocioso." }, "voice": { "type": "string", "enum": [ "male", "female", null ], "nullable": false, "description": "Voz da tradução, inclusive enquanto ocioso." }, "visible": { "type": "boolean", "description": "`true` mostra legendas; `false` as oculta. Também se aplica enquanto ocioso." }, "publisher": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "connect" ] }, "id": { "type": "string", "description": "ID do dispositivo quando `kind` é `connect`; ID do publicador do navegador quando `kind` é `browser`." }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ], "additionalProperties": false, "nullable": true, "description": "Dispositivo Kaleo Connect ou navegador que envia áudio; `null` enquanto ocioso." }, "phase": { "type": "string", "enum": [ "idle", "starting", "streaming", "reconnecting", "ending" ], "description": "Estágio da sessão; ocioso significa que nenhuma sessão está ativa." }, "streamSettings": { "type": "object", "description": "Padrões da igreja para o próximo início manual. Substituições da sessão ativa não alteram esses valores.", "required": [ "revision", "settings" ], "properties": { "revision": { "type": "integer", "minimum": 0, "description": "Aumenta quando esses padrões mudam." }, "settings": { "type": "object", "required": [ "speakerLanguage", "targetLanguages", "duration" ], "properties": { "speakerLanguage": { "type": "string", "description": "Código do idioma padrão do locutor." }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "Códigos padrão dos idiomas de tradução; `[\"ALL\"]` seleciona todos os alvos suportados." }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "Tempo até a parada automática, em segundos." } } } } } }, "required": [ "streaming", "phase", "sessionId", "startedAt", "deadlineAt", "speakerLanguage", "targetLanguages", "voice", "visible", "publisher", "streamSettings" ], "additionalProperties": false, "description": "Sessão atual e configurações compartilhadas da igreja. Todos os campos estão presentes, inclusive quando ocioso." }, "AdjustDeadline": { "type": "object", "additionalProperties": false, "required": [ "deltaSeconds" ], "properties": { "deltaSeconds": { "type": "integer", "minimum": -21600, "maximum": 21600, "description": "Segundos para adicionar à duração ociosa ou prazo atual; valores negativos subtraem. Não pode ser 0. Duração ociosa: 60–21600 segundos. Prazo ao vivo: futuro, dentro de seis horas de `startedAt`.", "not": { "enum": [ 0 ] } } } } } } }