Triage API

The Triage API powers Vantrexia's exception-based monitoring system. It provides risk-scored patient summaries, escalation management, vital sign alerts, per-patient threshold configuration, and a complete audit trail of all clinical decisions. The triage engine supports a 1:100 clinician-to-patient ratio by surfacing only patients who need attention.

Risk Score Range

Patient risk scores range from 0 to 100, calculated from vital sign deviations, alert frequency, and time since last review. Patients are categorized as: Critical (76–100), Warning (51–75), Normal (1–50), and No Data (0).

Triage Dashboard

Retrieve the triage dashboard with risk-scored patient summaries, sorted by severity. This is the primary endpoint for clinical workflow — it returns the priority-ranked list of patients requiring attention.

GET /api/v1/triage/patients/

Query Parameters

Parameter	Type	Required	Description
`risk_level`	`string`	No	Filter: `critical`, `warning`, `normal`, `no_data`
`has_unack_alerts`	`boolean`	No	Only patients with unacknowledged alerts
`ordering`	`string`	No	Sort: `-risk_score` (default), `last_reading_at`

Example Request

curl "https://app.vantrexia.com/api/v1/triage/patients/?risk_level=critical" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "patient_id": 23,
      "patient_name": "Robert Williams",
      "mrn": "MRN-00023",
      "risk_score": 92,
      "risk_level": "critical",
      "unacknowledged_alerts": 3,
      "latest_vitals": {
        "blood_pressure": { "systolic": 182, "diastolic": 108, "measured_at": "2026-02-06T14:30:00Z" },
        "weight": { "weight_kg": 95.2, "measured_at": "2026-02-06T07:00:00Z" }
      },
      "last_reviewed_at": "2026-02-05T16:00:00Z",
      "last_reviewed_by": "clinician@practice.com",
      "active_escalations": 1
    },
    {
      "patient_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "patient_name": "Mary Thompson",
      "mrn": "MRN-00007",
      "risk_score": 85,
      "risk_level": "critical",
      "unacknowledged_alerts": 2,
      "latest_vitals": {
        "blood_pressure": { "systolic": 168, "diastolic": 98, "measured_at": "2026-02-06T13:15:00Z" }
      },
      "last_reviewed_at": "2026-02-06T09:00:00Z",
      "last_reviewed_by": "clinician@practice.com",
      "active_escalations": 0
    }
  ]
}

Triage Summary

Retrieve aggregate triage statistics — patient counts by risk level, total alerts, and escalation counts.

GET /api/v1/triage/patients/stats/

Example Request

curl https://app.vantrexia.com/api/v1/triage/patients/stats/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "total_patients": 87,
  "patients_by_risk_level": {
    "critical": 4,
    "warning": 12,
    "normal": 43,
    "no_data": 28
  },
  "total_unacknowledged_alerts": 18,
  "active_escalations": 6,
  "avg_risk_score": 32.4,
  "patients_reviewed_today": 52,
  "patients_needing_review": 35
}

List Escalations

Retrieve escalation records with filtering by priority and status.

GET /api/v1/escalations/

Query Parameters

Parameter	Type	Required	Description
`priority`	`string`	No	Filter: `routine`, `urgent`, `stat`
`status`	`string`	No	Filter: `open`, `in_progress`, `resolved`, `cancelled`

Example Request

curl "https://app.vantrexia.com/api/v1/escalations/?priority=stat&status=open" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 2,
  "results": [
    {
      "id": 156,
      "patient_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "patient_name": "Robert Williams",
      "priority": "stat",
      "status": "open",
      "reason": "Systolic BP 182 mmHg — critical threshold exceeded, patient reporting headache",
      "created_by": "system",
      "created_at": "2026-02-06T14:30:05Z",
      "assigned_to": "clinician@practice.com",
      "updated_at": "2026-02-06T14:30:05Z"
    }
  ]
}

Create Escalation

Manually create a clinical escalation for a patient. Triggers notifications to assigned clinicians.

POST /api/v1/escalations/

Request Body

Parameter	Type	Required	Description
`patient_id`	`uuid`	Yes	Patient ID
`priority`	`string`	Yes	One of: `routine`, `urgent`, `stat`
`reason`	`string`	Yes	Clinical reason for escalation
`assigned_to`	`string`	No	Email of clinician to assign (default: primary clinician)

Example Request

curl -X POST https://app.vantrexia.com/api/v1/escalations/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
    "priority": "urgent",
    "reason": "Patient reports dizziness and chest tightness. BP trending upward over 3 days."
  }'

Response `201 Created`

{
  "id": 157,
  "patient_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "patient_name": "Mary Thompson",
  "priority": "urgent",
  "status": "open",
  "reason": "Patient reports dizziness and chest tightness. BP trending upward over 3 days.",
  "created_by": "clinician@practice.com",
  "created_at": "2026-02-06T15:00:00Z",
  "assigned_to": "clinician@practice.com"
}

Update Escalation

Update the status of an existing escalation. All status changes are audit-logged.

PATCH /api/v1/escalations/{id}/

Request Body

Parameter	Type	Required	Description
`status`	`string`	No	New status: `in_progress`, `resolved`, `cancelled`
`resolution_notes`	`string`	No	Notes about how the escalation was resolved

Example Request

curl -X PATCH https://app.vantrexia.com/api/v1/escalations/156/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution_notes": "Contacted patient. Instructed to take prescribed medication. Follow-up scheduled for tomorrow."
  }'

Response `200 OK`

{
  "id": 156,
  "patient_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "priority": "stat",
  "status": "resolved",
  "resolution_notes": "Contacted patient. Instructed to take prescribed medication. Follow-up scheduled for tomorrow.",
  "resolved_by": "clinician@practice.com",
  "resolved_at": "2026-02-06T15:15:00Z"
}

Threshold Change Logs

Retrieve the audit trail of all threshold configuration changes. Every modification to patient alert thresholds is recorded for compliance.

GET /api/v1/threshold-changes/

Example Request

curl "https://app.vantrexia.com/api/v1/threshold-changes/?patient_id=d290f1ee-6c54-4b01-90e6-d701748f0851" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 3,
  "results": [
    {
      "id": 45,
      "patient_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "changed_by": "clinician@practice.com",
      "changed_at": "2026-02-01T10:00:00Z",
      "field": "systolic_high",
      "old_value": 140,
      "new_value": 150,
      "reason": "Patient on new medication — temporarily raising threshold"
    }
  ]
}

Vital Sign Alerts

Retrieve active vital sign alerts. Alerts are automatically generated when device readings breach patient-specific thresholds.

GET /api/v1/alerts/

Query Parameters

Parameter	Type	Required	Description
`patient_id`	`uuid`	No	Filter by patient
`acknowledged`	`boolean`	No	Filter by acknowledgement status
`level`	`string`	No	Filter: `critical`, `warning`, `normal`, `no_data`

Example Request

curl "https://app.vantrexia.com/api/v1/alerts/?acknowledged=false&level=critical" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "count": 5,
  "results": [
    {
      "id": 892,
      "patient_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "patient_name": "Robert Williams",
      "level": "critical",
      "type": "blood_pressure",
      "message": "Systolic BP 182 mmHg exceeds critical threshold of 180 mmHg",
      "observation_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "value": 182,
      "threshold": 180,
      "acknowledged": false,
      "created_at": "2026-02-06T14:30:05Z"
    }
  ]
}

Acknowledge Alert

Acknowledge a vital sign alert. Acknowledged alerts are removed from the active queue and the action is audit-logged.

POST /api/v1/alerts/{id}/acknowledge/

Example Request

curl -X POST https://app.vantrexia.com/api/v1/alerts/892/acknowledge/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Reviewed reading. Patient contacted — will monitor closely."
  }'

Response `200 OK`

{
  "id": 892,
  "acknowledged": true,
  "acknowledged_by": "clinician@practice.com",
  "acknowledged_at": "2026-02-06T15:05:00Z",
  "notes": "Reviewed reading. Patient contacted — will monitor closely."
}

Get Patient Thresholds

Retrieve the alert threshold configuration for a specific patient.

GET /api/v1/patients/{uuid}/vital-config/

Example Request

curl https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/vital-config/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response `200 OK`

{
  "patient_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "blood_pressure": {
    "systolic_high": 150,
    "systolic_critical": 180,
    "systolic_low": 90,
    "diastolic_high": 90,
    "diastolic_critical": 110,
    "diastolic_low": 60
  },
  "pulse": {
    "high": 100,
    "critical": 120,
    "low": 50
  },
  "weight": {
    "change_threshold_kg": 2.0,
    "change_window_days": 3
  },
  "updated_at": "2026-02-01T10:00:00Z",
  "updated_by": "clinician@practice.com"
}

Update Patient Thresholds

Update the alert threshold configuration for a patient. A reason is required for audit logging. All changes are recorded in the threshold log.

PUT /api/v1/patients/{uuid}/vital-config/

Request Body

Parameter	Type	Required	Description
`blood_pressure`	`object`	No	BP thresholds (systolic_high, systolic_critical, etc.)
`pulse`	`object`	No	Pulse thresholds (high, critical, low)
`weight`	`object`	No	Weight change thresholds
`reason`	`string`	Yes	Clinical reason for the threshold change

Example Request

curl -X PUT https://app.vantrexia.com/api/v1/patients/d290f1ee-6c54-4b01-90e6-d701748f0851/vital-config/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "blood_pressure": {
      "systolic_high": 145,
      "systolic_critical": 180,
      "systolic_low": 90,
      "diastolic_high": 95,
      "diastolic_critical": 110,
      "diastolic_low": 60
    },
    "reason": "Adjusting BP thresholds — patient started on new antihypertensive"
  }'

Response `200 OK`

{
  "patient_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "blood_pressure": {
    "systolic_high": 145,
    "systolic_critical": 180,
    "systolic_low": 90,
    "diastolic_high": 95,
    "diastolic_critical": 110,
    "diastolic_low": 60
  },
  "pulse": {
    "high": 100,
    "critical": 120,
    "low": 50
  },
  "weight": {
    "change_threshold_kg": 2.0,
    "change_window_days": 3
  },
  "updated_at": "2026-02-06T15:20:00Z",
  "updated_by": "clinician@practice.com"
}

Audit Trail

Every threshold change is recorded with the old value, new value, who made the change, and why. View the complete history via the Threshold Change Logs endpoint.

Previous Billing API Next FHIR API

Triage Dashboard

Query Parameters

Example Request

Response 200 OK

Triage Summary

Example Request

Response 200 OK

List Escalations

Query Parameters

Example Request

Response 200 OK

Create Escalation

Request Body

Example Request

Response 201 Created

Update Escalation

Request Body

Example Request

Response 200 OK

Threshold Change Logs

Example Request

Response 200 OK

Vital Sign Alerts

Query Parameters

Example Request

Response 200 OK

Acknowledge Alert

Example Request

Response 200 OK

Get Patient Thresholds

Example Request

Response 200 OK

Update Patient Thresholds

Request Body

Example Request

Response 200 OK

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`