Investigate V2 é um sistema que recebe o message_id junto com generalInstructions do gestor, processa a resposta e explica porque a IA respondeu daquele jeito.

​
📑 Índice

​
🎯 Visão Geral

​
Endpoint

POST /api/externalAPIs/public/investigateV2

​
Funcionalidades Principais

​
🔑 Autenticação

Todas as requisições requerem autenticação através do middleware tolkyAuthMiddleware. Certifique-se de incluir o token Bearer no header Authorization.

​
Cabeçalhos Obrigatórios

Authorization: Bearer <seu_token_aqui>
Content-Type: application/json

​
⚙️ Parâmetros da Requisição

​
Body (JSON)

CampoTipoObrigatórioDescrição
message_idstring (UUID)SimUUID da mensagem a ser investigada
messageIdstring (UUID)NãoAlias em camelCase de message_id (aceito também)
generalInstructionsstringSimInstruções/questionamento do gestor sobre a resposta da IA
general_instructionsstringNãoAlias em snake_case de generalInstructions (aceito também)
callerstringNãoFiltra quais registros de public.cost_control serão considerados pelo caller (ex: "createAssistantResponse"). Se informado, o endpoint também garante que createAssistantResponse será incluído na análise principal.
callersstring[] | stringNãoVersão “avançada” do filtro por caller. Pode ser uma string (será convertida para array) ou um array de callers. Mesmo que você passe outros callers, createAssistantResponse sempre é incluído.

​
📦 Formato de Resposta

A resposta segue o formato JSON abaixo:

{
  "summary": "string - resumo do que foi encontrado na análise do prompt com a conversa entre o usuário e a IA e o response",
  "snippets": [
    {
      "snippet": "string - trecho do texto que foi encontrado nas instruções ou na conversa",
      "explanation": "string - explicação de porque o trecho influenciou na resposta da IA",
      "relevance": "number - relevância do trecho de 0 a 10. Se possível, é importante que cada item do array possa ter uma relevância diferente para evitar encavalamento no front."
    }
  ]
}

​
Campos da Resposta

CampoTipoDescrição
summarystringResumo do que foi encontrado na análise do prompt com a conversa entre o usuário e a IA e o response
snippetsarrayArray de objetos contendo trechos relevantes encontrados
snippets[].snippetstringTrecho do texto que foi encontrado nas instruções ou na conversa
snippets[].explanationstringExplicação de porque o trecho influenciou na resposta da IA
snippets[].relevancenumberRelevância do trecho de 0 a 10. Cada item do array pode ter uma relevância diferente para evitar encavalamento no front

​
💡 Exemplos de Uso

  • 📤 Requisição Básica

  • 📤 Com Caller

  • 📤 Múltiplos Callers

  • 📤 Usando Aliases

  • 📥 Resposta de Exemplo

curl -X POST \
  '{BASE_URL}/api/externalAPIs/public/investigateV2' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -d '{
    "message_id": "123e4567-e89b-12d3-a456-426614174000",
    "generalInstructions": "Por que a IA respondeu de forma tão formal nesta mensagem?"
  }'

​
⚠️ Códigos de Erro

CódigoDescrição
400Bad Request - Parâmetros obrigatórios ausentes ou inválidos
401Unauthorized - Token de autenticação inválido ou ausente
403Forbidden - Credenciais inválidas
404Not Found - Mensagem ou cost_control não encontrado
500Internal Server Error - Erro interno do servidor

​
🔄 Endpoints Relacionados

​
Investigate Message (V1)

Para investigação detalhada de mensagens com dados completos de processamento e métricas.

Endpoint: POST /api/externalAPIs/public/investigateMessage

Ver documentação completa

​
Tolky Reasoning

Para processamento de perguntas e respostas contextualizadas utilizando a inteligência do Tolky.

Endpoint: POST /api/externalAPIs/public/tolkyReasoning/callReasoning

Ver documentação completa

Investigar Mensagem por IDListar Avatares