POST /api/v1/chat/message

Chat direto com o agente SauBit para tirar dúvidas clínicas e discutir riscos/monitorização.

Cada mensagem enviada é uma transação faturável (preço configurável no admin).

Este endpoint também pode disparar webhooks (chat.message) quando configurados.

informação

Atalho: você também pode usar POST /api/v1/chat (alias de /api/v1/chat/message).

Cabeçalhos

• X-API-Key: sm_live_...
• Content-Type: application/json

Body

{
  "session_id": "opcional-para-continuar-a-conversa",
  "message": "Paciente em hemodiálise pode usar este medicamento? Quais riscos e monitorização?",
  "analysis_id": "opcional-para-referenciar-uma-analise-anterior"
}

Observações de segurança

• Se analysis_id for enviado, ele deve pertencer à mesma organização da sua X-API-Key (caso contrário retorna 404).
• Quando analysis_id é usado como contexto, o chat filtra menções a fontes não verificadas (por exemplo, remove PMIDs/DOIs que não aparecem nas references da análise referenciada).

Resposta 200

Além de session_id e answer, a resposta traz um contrato clínico estruturado:

{
  "session_id": "abc123",
  "answer": "...",
  "mode": "analysis_grounded",
  "analysis_id": "a1b2c3...",
  "recommendation_level": "avoid_combination",
  "requires_professional_review": true,
  "not_assessed": ["renal_adjustment"],
  "uncertainties": ["weight"],
  "references": [ { "source": "pubmed", "pmid": "12345678", "url": "https://..." } ],
  "versions": { "rules_version": "...", "model_version": "..." },
  "billing_status": "charged"
}

Campo	Significado
mode	analysis_grounded (ancorado numa análise via analysis_id) ou educational (orientação geral, não individualizada, quando não há analysis_id).
requires_professional_review	Sempre true — apoio à decisão, não substitui o prescritor.
recommendation_level · not_assessed · uncertainties	Herdados da análise referenciada (nível de conduta, domínios não avaliados, dados ausentes).
references	Fontes verificadas da análise (PMID/URL).
billing_status	charged ou not_charged (chave de teste/sandbox).
response_view	Papel usado para adaptar a resposta: physician/medico ou pharmacist/farmaceutico, quando resolvido (ver abaixo). null quando nenhum papel é resolvido — resposta neutra.

Sem analysis_id, o mode é educational: a resposta é conteúdo geral, não aconselhamento individualizado sobre um paciente específico.

Resposta adaptada por papel (response_view)

Quando um papel é resolvido, o texto de answer é adaptado: para médico, prioriza mecanismo de ação, farmacocinética e impacto na decisão terapêutica; para farmacêutico, prioriza interação, ajuste de dose, compatibilidade/estabilidade e aspectos de dispensação. A resolução do papel segue exatamente a mesma regra de segurança da governança de alertas (B4):

1. Se a API key tiver um papel vinculado (alert_view configurado no admin), ele é sempre usado — o header abaixo é ignorado.
2. Senão, o header X-SauBit-Alert-View: physician (ou pharmacist) é usado como sinal livre.
3. Se nenhum dos dois estiver presente, a resposta é neutra (response_view: null).

curl -X POST https://api.saubit.com.br/api/v1/chat/message \
  -H "X-API-Key: sm_live_..." \
  -H "X-SauBit-Alert-View: pharmacist" \
  -H "Content-Type: application/json" \
  -d '{"message": "Qual o risco desta combinação?", "analysis_id": "a1b2c3..."}'

Resposta 200 (exemplo real)

{
  "session_id": "45e9559bf7c14b17acdcf5d0690a5d65",
  "answer": "A associação de varfarina com aspirina apresenta um risco grave de sangramento devido ao efeito hemostático aditivo... Monitorização: acompanhar INR e sinais de sangramento. Conduta: evitar a combinação e encaminhar para revisão profissional."
}

A resposta tem sempre dois campos: session_id (use-o para continuar a conversa) e answer (texto clínico). A resposta é ancorada nas fontes da sessão e em uma base curada de interações; menções a fontes não verificadas são filtradas.

Respostas de erro

HTTP	detail
401	API key required
403	Scope insuficiente para esta API key
404	Análise não encontrada (quando analysis_id não pertence à sua organização)
422	message ausente/ inválido
429	Rate limit excedido

// 404 — analysis_id de outra organização
{ "detail": "Análise não encontrada" }

Catálogo completo: Respostas e Códigos de Erro.