POST /api/v1/chat/message

Direct chat with the SauBit agent to answer clinical questions and discuss risks/monitoring.

Each message is a billable transaction (price configurable in Admin). This endpoint may also trigger webhooks (chat.message) when configured.

info

Shortcut: you can also use POST /api/v1/chat (alias of /api/v1/chat/message).

Headers

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

Body

{
  "session_id": "optional-to-continue-the-conversation",
  "message": "Can a patient on hemodialysis use this medication? What are the risks and monitoring?",
  "analysis_id": "optional-to-reference-a-previous-analysis"
}

Security notes

• If analysis_id is sent, it must belong to the same organization as your X-API-Key (otherwise it returns 404).
• When analysis_id is used as context, the chat filters out mentions of unverified sources (e.g. removes PMIDs/DOIs that do not appear in the referenced analysis' references).

Response 200 (structured contract)

Beyond session_id and answer, the response carries a structured clinical contract:

{
  "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"
}

Field	Meaning
mode	analysis_grounded (tied to an analysis via analysis_id) or educational (general, non-individualized guidance when no analysis_id).
requires_professional_review	Always true — decision support, not a substitute for the prescriber.
recommendation_level · not_assessed · uncertainties	Inherited from the referenced analysis.
references	Verified sources from the analysis (PMID/URL).
billing_status	charged or not_charged (test/sandbox key).
response_view	Role used to tailor the answer: physician/medico or pharmacist/farmaceutico, when resolved (see below). null when no role is resolved — neutral answer.

Without analysis_id, mode is educational: a general answer, not individualized advice about a specific patient.

Role-tailored answer (response_view)

When a role is resolved, the answer text is tailored: for physician, it prioritizes mechanism of action, pharmacokinetics and impact on the therapeutic decision; for pharmacist, it prioritizes drug interaction, dose adjustment, compatibility/stability and dispensing aspects. Role resolution follows the exact same security rule as alert governance (B4):

1. If the API key has a bound role (alert_view configured in Admin), it is always used — the header below is ignored.
2. Otherwise, the X-SauBit-Alert-View: physician (or pharmacist) header is used as a free signal.
3. If neither is present, the answer is neutral (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": "What is the risk of this combination?", "analysis_id": "a1b2c3..."}'

Response 200 (real example)

{
  "session_id": "45e9559bf7c14b17acdcf5d0690a5d65",
  "answer": "Combining warfarin with aspirin carries a severe bleeding risk due to the additive hemostatic effect... Monitoring: follow INR and signs of bleeding. Action: avoid the combination and refer for professional review."
}

The response always has two fields: session_id (use it to continue the conversation) and answer (clinical text). The answer is grounded in the session's sources and a curated interaction base; mentions of unverified sources are filtered out.

Error responses

HTTP	detail
401	API key required
403	Scope insuficiente para esta API key
404	Análise não encontrada (when analysis_id does not belong to your organization)
422	message missing/invalid
429	Rate limit excedido

// 404 — analysis_id from another organization
{ "detail": "Análise não encontrada" }

See the full catalog in Responses & Error Codes.