POST /api/v1/interactions/compare

Compares 2 to 5 candidate medications against the same patient context, to support choosing between therapeutic alternatives (e.g. "which is safer for this patient: A or B?").

Each candidate is evaluated independently, as if it were added to patient_record.current_medications — the same deterministic engine used by /interactions/check, one full analysis per candidate. Each candidate counts as its own billable analysis (same behavior as /interactions/batch).

What this endpoint does NOT do

It does not evaluate interaction between the candidates themselves — they would not be prescribed together. Each candidate is compared against the patient's current regimen, not against each other.

Headers

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

Body

{
  "candidates": ["Ibuprofen", "Paracetamol"],
  "patient_record": {
    "current_medications": [{"name": "Warfarin"}],
    "conditions": ["atrial fibrillation"]
  },
  "include_mild": true,
  "language": "pt-BR"
}

Field	Required	Description
candidates	Yes	2 to 5 medication names, no duplicates.
patient_record	No	Same schema as /interactions/check — current_medications is used as the base for each candidate.
patient_context	No	Same schema as /interactions/check.
include_mild	No (default true)	Include LEVE (mild) alerts in each candidate's analysis.
language	No (default pt-BR)

Response 200

{
  "candidates_evaluated": ["Ibuprofen", "Paracetamol"],
  "comparisons": [
    {
      "candidate": "Ibuprofen",
      "analysis_id": "uuid-1",
      "prescription_risk_level": "HIGH",
      "prescription_score": 82,
      "interactions_count": 0,
      "clinical_alerts_count": 1,
      "top_alerts": ["NSAID increases gastrointestinal bleeding risk."],
      "summary": "Complete analysis with interactions and required coverage met."
    },
    {
      "candidate": "Paracetamol",
      "analysis_id": "uuid-2",
      "prescription_risk_level": "LOW",
      "prescription_score": 0,
      "interactions_count": 0,
      "clinical_alerts_count": 0,
      "top_alerts": [],
      "summary": "Complete analysis with no known interactions for the checked pairs."
    }
  ],
  "safer_candidate": "Paracetamol",
  "recommendation": "Paracetamol showed the lowest relative risk (LOW) for this patient among the evaluated candidates. Professional review is mandatory before any therapeutic decision.",
  "safety_notice": "This comparison is decision support, it does not replace clinical judgment. ..."
}

Each candidate's analysis_id can later be used with /interactions/recheck, /interactions/alerts/decision, /chat/message (analysis_id) and /analyses/{analysis_id}, exactly like any other analysis.

Notes

• Required scope: interactions:check (same as /interactions/check).
• safer_candidate is only populated when there is a clear risk difference between candidates; on a tie it is null and the recommendation points to considering other clinical factors.
• Every internal call uses processing_options.context_mode = "stateless" — the comparator never updates the patient's persistent Clinical Context, even if the organization's policy allows persistence.

Other error responses

HTTP	detail
401	API key required
403	Scope insuficiente para esta API key
422	fewer than 2 candidates, duplicate candidates, or more than 5
429	Rate limit excedido
504	Some candidate exceeded the analysis time limit.

Full catalog: Responses & Error Codes.