Health APIs

Async job APIs for point-of-care triage, clinical decision support, wellness coaching, and neuro decode — all following the same POST → 202 job_id → poll pattern.

Health APIs

All Pi health endpoints follow the same async job pattern:

1. POST with Authorization: Bearer <api_key> and a JSON body.
2. Response 202 with { object: "job", data: { job_id } }.
3. Poll GET /api/v1/jobs/:id?wait_for_completion=true for payload.output.

Pi health outputs are decision-support and workflow assistance only. They are not a substitute for licensed clinical judgment, radiology reads, or pharmacy verification. Do not use outputs as the sole basis for clinical decisions without proper validation and regulatory review.

Point-of-care triage

POST /api/v1/health/analyze accepts a medical image or raw EEG payload and returns an async triage report — findings, triage level, treatment plan, and referral recommendation.

Image triage (X-ray / skin)

curl -sS -X POST "$BASE/api/v1/health/analyze" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "image",
      "data": "data:image/jpeg;base64,<...> OR https://.../image.jpg",
      "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
    }
  }'

EEG triage (epilepsy screening)

curl -sS -X POST "$BASE/api/v1/health/analyze" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "eeg",
      "data": "<base64|json>",
      "modality": "eeg"
    },
    "context": {
      "locale": "en"
    },
    "output": {
      "format": "json",
      "include_diagnostics": false
    }
  }'

Response (202)

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

Poll and read the triage report

curl -sS "$BASE/api/v1/jobs/$job_id?wait_for_completion=true&timeout_seconds=20" \
  -H "Authorization: Bearer $PI_API_KEY"

Completed payload.output example:

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

Add include=diagnostics to the poll URL when debugging backend routing.

Decision suite (7 endpoints)

All seven endpoints accept POST, return 202 + job_id, and use the same poll pattern as triage.

Endpoint	Purpose
POST /api/v1/health/risk-priority	Vitals/history JSON → risk_level, next_action, recommended_actions
POST /api/v1/health/adherence	Treatment timeline JSON → adherence_risk, next_action, missed_items
POST /api/v1/health/notes-structure	Free-text clinical notes → symptoms, conditions, meds, timeline, coding hints
POST /api/v1/health/decision-support	Clinical situation JSON → recommended_action, reasoning, safety flags
POST /api/v1/health/medication-check	Medication list JSON → interactions, contraindications, next_action
POST /api/v1/health/scan-analysis	Image + modality → structured findings + patient-friendly explanation
POST /api/v1/health/research-assist	Research JSON (+ optional dataset attachment) → analysis, methods review, next steps

Example: patient risk priority

curl -sS -X POST "$BASE/api/v1/health/risk-priority" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "patient_data",
      "data": "{\"vitals\":{\"hr\":110},\"complaint\":\"chest pain\"}"
    },
    "output": { "include_diagnostics": true }
  }'

Example: medication check (TypeScript)

const BASE = process.env.PI_BASE_URL ?? "https://api.example.com";
const API_KEY = process.env.PI_API_KEY!;

async function pi(path: string, body: unknown) {
  const res = await fetch(`${BASE}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json?.error?.message ?? "request failed");
  return json;
}

// Submit medication check
const job = await pi("/api/v1/health/medication-check", {
  input: {
    type: "medication_list",
    data: JSON.stringify({
      medications: ["warfarin 5mg", "aspirin 81mg", "ibuprofen 400mg"],
      patient_age: 68,
      indication: "atrial fibrillation",
    }),
  },
  output: { include_diagnostics: false },
});

// Poll result
const result = await fetch(
  `${BASE}/api/v1/jobs/${job.data.job_id}?wait_for_completion=true&timeout_seconds=30`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then((r) => r.json());

console.log(result.data.payload.output);

Enable or disable individual decision endpoints with feature flags in your server environment. Setting MEDICATION_CHECK_ENABLED=false, for example, returns 403 for that route while leaving others active.

Wellness (EEG + optional vision)

POST /api/v1/health/wellness runs an async wellness analysis from EEG data — focus/burnout coaching, stress bands, fatigue estimates. Optionally attach a screenshot for vision-assisted synthesis.

curl -sS -X POST "$BASE/api/v1/health/wellness" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "eeg",
      "data": "'"$B64"'",
      "modality": "cognitive_wellness",
      "device": "Consumer headset",
      "channels": 8,
      "sample_rate": 250
    },
    "context": {
      "locale": "en",
      "session_goal": "post_work_decompression",
      "self_reported_stress": 6
    },
    "output": { "format": "json", "include_diagnostics": true }
  }'

Completed payload.output includes:

{
  "wellness_summary": "Signals suggest moderate fatigue with workable attention reserves.",
  "stress_band": "moderate",
  "fatigue_estimate": 0.62,
  "coaching_message": "Try a 5-minute breathing reset before the next task block.",
  "recommendations": [
    "Short walk or stretch",
    "Reduce parallel notifications for 20 minutes"
  ],
  "risk_flags": [],
  "seizure_detected": false,
  "disclaimer": "This output is for wellness..."
}

Neuro decode (EEG intent)

POST /api/v1/neuro/decode decodes EEG signals into structured intents for accessibility and BCI applications — motor imagery, P300, SSVEP, and more.

curl

curl -sS -X POST "$BASE/api/v1/neuro/decode" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "eeg",
      "data": "dGVzdA==",
      "paradigm": "motor_imagery"
    },
    "output": { "include_diagnostics": true }
  }'

Completed payload example:

{
  "decoded_intent": "move_left",
  "confidence": 0.82,
  "paradigm_detected": "motor_imagery",
  "predicted_text": "Turn left toward the door",
  "alternatives": [
    { "intent": "rest", "confidence": 0.12 },
    { "intent": "move_right", "confidence": 0.06 }
  ],
  "seizure_detected": false,
  "disclaimer": "BCI outputs are probabilistic..."
}

BCI decode outputs are probabilistic. Use human oversight and hardware/software interlocks for any physical actuation (wheelchairs, doors, medication dispensers).

Poll reference

All health endpoints share the same job polling URL:

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

Add include=diagnostics when debugging to receive per-step timings and routing fallback details in the response.

Related

• Health Triage API reference
• Health Decision Suite API reference
• Cognitive Wellness API reference
• Neuro Decode API reference
• Jobs API reference