Health Triage

Submit medical images or EEG data for async point-of-care triage support.

Health Triage

POST /api/v1/health/analyze

Send a medical image (X-ray, ultrasound, skin lesion) or raw EEG data from a portable headset. Pi queues an async job and returns a job_id you use to poll for the structured triage report.

This endpoint provides triage support only. It is not a substitute for professional medical diagnosis, clinical guidelines, or local referral pathways. If danger signs are present, seek urgent care immediately.

Request

curl

curl -sS -X POST "$PI_BASE_URL/api/v1/health/analyze" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "image",
      "data": "data:image/jpeg;base64,<...>",
      "modality": "xray",
      "mime_type": "image/jpeg"
    },
    "context": {
      "patient_age": 45,
      "symptoms": "persistent cough, weight loss",
      "duration_days": 21,
      "pregnant": false,
      "locale": "sw-KE"
    },
    "output": {
      "locale": "sw-KE",
      "format": "json",
      "include_diagnostics": false
    }
  }'

Body parameters

input · object · required

The clinical payload to analyze.

Show input fields

input.type · string · required

Input modality type. One of "image" or "eeg".

input.data · string · required

For images: base64-encoded data (with optional data: prefix) or an https:// URL. For EEG: base64-encoded binary payload or a JSON-stringified buffer. Max 8 MB.

input.modality · string

Free-form modality hint. Required when type is "image". Examples: "xray", "ultrasound", "skin_lesion", "ct_scan", "eeg". Max 64 characters.

input.mime_type · string

MIME type hint for image payloads, e.g. "image/jpeg". Max 128 characters.

context · object

Arbitrary JSON context passed to the triage engine. Useful for patient age, symptoms, duration, pregnancy status, locale, and any other clinical metadata. Must serialize to at most 16,000 characters.

output · object

Controls the response format.

Show output fields

output.locale · string

BCP-47 locale code for the response language, e.g. "sw-KE", "en". Between 2 and 32 characters.

output.format · string

Response format. One of "report" or "json". Defaults to "report".

output.include_diagnostics · boolean

When true, the completed job payload includes per-step timing and routing details. Use for monitoring and debugging only. Defaults to false.

Response

Returns 202 Accepted immediately. Poll GET /api/v1/jobs/:id for the result.

{
  "id": "req_pi_<uuid>",
  "object": "job",
  "status": "queued",
  "created_at": 1711700000,
  "data": { "job_id": "<uuid>" }
}

Polling for results

Use the Jobs endpoint with long-polling to retrieve the completed triage report:

GET /api/v1/jobs/:id?wait_for_completion=true&timeout_seconds=20

Add include=diagnostics when debugging routing and step timing.

Completed job output

When the job reaches completed, data.payload.output contains the triage report:

triage_level · string

Urgency classification. One of "critical", "urgent", "standard", or "low".

confidence · number

Overall confidence score between 0 and 1.

locale · string

Locale used for the response text.

findings · array

Array of structured clinical findings. Each item contains title, summary, confidence, and evidence.

segmentation_overlay_url · string | null

URL to an annotated segmentation overlay image when the MONAI sidecar is configured. null otherwise.

seizure_detected · boolean | null

Seizure flag from the EEG classification step. null for image inputs or when the MetaBCI sidecar is unavailable.

treatment_plan · string

Supportive care guidance including when to refer, in the requested locale.

referral_recommendation · string

Referral guidance based on severity and findings.

red_flags · array

List of warning signs that require urgent escalation.

disclaimer · string

Mandatory disclaimer text indicating this is triage support, not a diagnosis.

Example completed output:

{
  "triage_level": "urgent",
  "confidence": 0.82,
  "locale": "sw-KE",
  "findings": [
    {
      "title": "Possible lower respiratory infection",
      "summary": "Imaging features and symptoms could be consistent with infection; confirm with exam and local guidelines.",
      "confidence": 0.61,
      "evidence": ["cough > 14 days", "systemic symptoms"]
    }
  ],
  "segmentation_overlay_url": null,
  "seizure_detected": null,
  "treatment_plan": "Supportive care steps, when to refer, and culturally appropriate instructions.",
  "referral_recommendation": "Refer urgently if severe respiratory distress, altered mental status, or hypoxia is suspected.",
  "red_flags": ["severe shortness of breath", "confusion", "cyanosis"],
  "disclaimer": "This tool provides triage support only and is not a medical diagnosis. Seek urgent care if red flags are present."
}

Use cases

Smartphone-to-diagnosis (X-ray / ultrasound / skin lesion)

Set input.type to "image" and provide a base64 image or URL. Use input.modality to indicate the image type. The response includes structured findings, triage level, and an optional segmentation overlay when the MONAI sidecar is running.

Low-cost epilepsy screening (EEG)

Set input.type to "eeg" and provide a base64-encoded EEG payload. The response includes a seizure flag (when MetaBCI is configured) and a care plan for the local health worker.

Error codes

Code	HTTP	Description
missing_authorization_header	401	No Authorization header present
invalid_request_body	400	Schema validation failed (e.g. missing modality for image input)
health_triage_disabled	403	HEALTH_TRIAGE_ENABLED=false in server environment
job_create_failed	500	Database insert failed
job_trigger_failed	502	Background worker not reachable