Skip to main content

​
Cognitive Wellness

POST /api/v1/health/wellness Send an EEG payload with optional session context and an optional screenshot. Pi returns a wellness summary, stress band, fatigue estimate, and personalized coaching recommendations — all via an async job.
This endpoint provides wellness coaching support. It is not clinical treatment or a psychiatric diagnosis. Stress bands and fatigue estimates are heuristic labels, not validated clinical scales. Honor risk_flags in your UI and encourage users to seek qualified care when appropriate.

​
Request

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

​
Body parameters

​
input
object
required
The EEG payload and session metadata.
​
context
object
Arbitrary JSON session context. Include goals (session_goal), self-reported stress (self_reported_stress 0–10), game metrics, locale, and app identifiers. Must serialize to at most 16,000 characters.
​
output
object

​
Response

Returns 202 Accepted. An optional Idempotency-Key header is supported; scope is health_wellness. 
{
  "id": "req_pi_<uuid>",
  "object": "job",
  "status": "queued",
  "created_at": 1711700000,
  "data": { "job_id": "<uuid>" }
}

​
Polling for results

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

​
Completed job output

​
wellness_summary
string
A brief, human-readable narrative of the session’s cognitive state.
​
stress_band
string
Heuristic stress label, e.g. "low", "moderate", "elevated". Not a clinical scale.
​
fatigue_estimate
number
Fatigue proxy between 0 (alert) and 1 (high fatigue).
​
coaching_message
string
Personalized coaching message for the user.
​
recommendations
array
List of actionable wellness recommendations, e.g. stretch breaks, breathing exercises.
​
clinical_style_summary
string
Optional clinician-oriented summary when MedGemma is configured. Notes that EEG patterns are non-diagnostic.
​
risk_flags
array
Signals that warrant surfacing in your UX, e.g. indicators suggesting professional consultation.
​
seizure_detected
boolean | null
Seizure flag from the MetaBCI sidecar when configured. null when unavailable.
​
metadata
object
Session metadata including paradigm, has_image, and attention_proxy.
​
disclaimer
string
Mandatory disclaimer text.
Example: 
{
  "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"
  ],
  "clinical_style_summary": "User-reported stress elevated; EEG envelope consistent with non-specific fatigue pattern — not diagnostic.",
  "risk_flags": [],
  "seizure_detected": false,
  "disclaimer": "This output is for wellness coaching purposes only.",
  "metadata": {
    "paradigm": "cognitive_wellness",
    "has_image": false,
    "attention_proxy": 0.55
  }
}

​
Use cases

Focus / burnout-adjacent coaching Pass context.session_goal (e.g. "post_work_decompression") and optionally context.self_reported_stress. The response coaching message and recommendations are tailored to the stated goal. Cognitive game / UI-assisted sessions Include input.image_data with a screenshot of the game or task interface. When HuatuoGPT is configured, the vision branch merges UI context into the wellness narrative. Diagnostics will show vision routing when enabled.