Base de conhecimento
Documentos e conversas da base de conhecimento interna.
Consultar recursos da base de conhecimento
Informa se a base de conhecimento está ativa na organização e o que você pode fazer: ler, gerenciar e publicar documentos, usar o chat e gerenciar configurações. Disponível para qualquer pessoa autenticada em uma organização.
Listar empresas da base de conhecimento
Lista as empresas às quais você tem acesso na base de conhecimento. Listagem paginada no envelope `{items, page}` com `limit`, `cursor`, ordenação e filtros permitidos. Requer uma das permissões `knowledge.chat.use`, `knowledge.documents.read` ou `knowledge.documents.manage`.
Listar conversas da empresa
Lista as suas conversas com o assistente na empresa informada, com total de mensagens e a última pergunta. O identificador no caminho é o código público de 4 caracteres. Listagem paginada no envelope `{items, page}` com `limit`, `cursor`, ordenação e filtros permitidos. Requer a permissão `knowledge.chat.use`.
Criar conversa
Cria uma conversa com o assistente na empresa informada, usando `request_nonce` como identificador; repetir o mesmo nonce devolve a mesma conversa. Cada pessoa pode ter até 100 conversas por empresa (`429` `knowledge_quota_exceeded`). O `company_id` no caminho é o código público da empresa. Requer a permissão `knowledge.chat.use`.
Consultar conversa
Retorna uma conversa sua, com título, estado de arquivamento, versão e total de mensagens. Conversa de outra pessoa ou inexistente retorna `404`. O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.chat.use`.
Excluir conversa
Exclui definitivamente uma conversa sua e responde `204`. Conversa de outra pessoa ou inexistente retorna `404`. O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.chat.use`.
Atualizar conversa
Renomeia (`title`) ou arquiva e restaura (`archived`) uma conversa sua. Usa concorrência otimista por `expected_version` (versão divergente retorna `409`); não é possível arquivar enquanto uma resposta está sendo gerada (`409` `knowledge_in_progress`). O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.chat.use`.
Listar mensagens da conversa
Lista as perguntas e respostas de uma conversa sua. O identificador no caminho é o código público de 4 caracteres. Listagem paginada no envelope `{items, page}` com `limit`, `cursor`, ordenação e filtros permitidos. Requer a permissão `knowledge.chat.use`.
Enviar pergunta ao assistente
Envia uma pergunta (até 4000 caracteres) e retorna a resposta do assistente, baseada nos documentos publicados da empresa, com citações. Idempotente por `request_nonce`, com limite de 20 perguntas por minuto; cota diária de uso esgotada retorna `429` `knowledge_quota_exceeded`, conversa arquivada ou com resposta em andamento retorna `409` e indisponibilidade do provedor de IA retorna `503`. O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.chat.use`.
Consultar perfil do assistente
Retorna as preferências do assistente para a empresa (nome, mensagem de boas-vindas, perguntas sugeridas, estilo de resposta), com o nome da empresa e o total de documentos publicados. O `company_id` no caminho é o código público da empresa. Requer a permissão `knowledge.chat.use`.
Listar documentos da base de conhecimento
Lista os documentos que você pode ler, com estado, empresas vinculadas e se você pode gerenciar ou publicar cada um; filtre por empresa com `company_id`. Listagem paginada no envelope `{items, page}` com `limit`, `cursor`, ordenação e filtros permitidos. Requer a permissão `knowledge.documents.read`.
Criar documento
Registra um documento (PDF ou texto, até 10 MiB) vinculado a 1 a 50 empresas e retorna seu código; o conteúdo é enviado em seguida. Idempotente por `request_nonce`: reutilizar o nonce com outros dados retorna `409`. A organização aceita até 1000 documentos e 500 MB no total (`429` `knowledge_quota_exceeded`). Requer a permissão `knowledge.documents.manage`.
Consultar documento
Retorna os dados de um documento da base de conhecimento, com estado, versão, páginas e empresas vinculadas. Documento inexistente ou fora do seu acesso retorna `404`. O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.documents.read`.
Enviar conteúdo do documento
Envia o arquivo do documento no corpo da requisição; o tamanho deve ser igual a `size_bytes` informado na criação e o conteúdo precisa ser um PDF válido ou texto UTF-8 (senão `422` `knowledge_file_invalid`). Só é aceito enquanto o documento aguarda envio (senão `409`); depois ele entra na fila de processamento. O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.documents.manage`.
Baixar documento
Baixa o arquivo original do documento como anexo, sem cache. Documento inexistente ou fora do seu acesso retorna `404`. O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.documents.read`.
Publicar, despublicar ou remover documento
Aplica `publish`, `unpublish` ou `remove` ao documento. Publicar exige o documento pronto e despublicar exige ele publicado; estado incompatível ou `expected_version` divergente retorna `409`. O identificador no caminho é o código público de 4 caracteres. Publicar e despublicar requerem `knowledge.documents.publish`; remover requer `knowledge.documents.manage`.
Definir empresas do documento
Substitui as empresas vinculadas ao documento (1 a 50). Se o documento já está publicado, também exige `knowledge.documents.publish` nas empresas informadas, e usa concorrência otimista por `expected_version` (versão divergente retorna `409`). O identificador no caminho é o código público de 4 caracteres. Requer a permissão `knowledge.documents.manage`.
Consultar configurações da base de conhecimento
Retorna as configurações da organização: limite diário de tokens (e o limite efetivo aplicado), nome do assistente, boas-vindas, perguntas sugeridas, estilo de resposta e retenção de conversas. Requer uma das permissões `knowledge.chat.use` ou `knowledge.settings.manage`.
Atualizar configurações da base de conhecimento
Substitui as configurações da base de conhecimento: limite diário de tokens, nome do assistente, boas-vindas, até 4 perguntas sugeridas, estilo de resposta, retenção de 7 a 365 dias e acesso pelo público externo. Usa concorrência otimista por `expected_version` (versão divergente retorna `409`). Requer a permissão `knowledge.settings.manage` e, para pessoas, acesso a todas as empresas ou ser titular ou gestor da conta.