Neuro Decode

Async BCI/EEG intent decoding for mobility assistance, mind-to-speech, and accessibility applications.

Neuro Decode

POST /api/v1/neuro/decode

Send raw EEG payloads from consumer or clinical headsets. Pi decodes the intended action or character, returns optional predictive text, and surfaces an alternative intent ranking — all in a single async job.

BCI outputs are probabilistic and not a medical diagnosis. Always apply human oversight and hardware/software interlocks before acting on decoded intents for wheelchairs, doors, medication workflows, or any safety-critical system.

Request

curl

curl -sS -X POST "$PI_BASE_URL/api/v1/neuro/decode" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "eeg",
      "data": "dGVzdA==",
      "paradigm": "motor_imagery",
      "device": "OpenBCI Cyton",
      "channels": 8,
      "sample_rate": 250
    },
    "context": {
      "locale": "en",
      "session_history": ["move_left", "rest", "move_right"],
      "ui_mode": "wheelchair_nav"
    },
    "output": {
      "format": "json",
      "include_diagnostics": false
    }
  }'

Body parameters

input · object · required

The EEG payload and device metadata.

Show input fields

input.type · string · required

Must be "eeg".

input.data · string · required

Base64-encoded binary EEG payload or a JSON-stringified array/tensor metadata structure. Max 8 MB.

input.paradigm · string · required

BCI paradigm hint. Common values: "motor_imagery", "p300", "ssvep", "erp". Unknown values are accepted; Pi adapts prompts accordingly. Max 128 characters.

input.device · string

Headset model or device identifier, e.g. "OpenBCI Cyton", "Muse 2". Max 128 characters.

input.channels · integer

Number of EEG channels. Between 1 and 1,024.

input.sample_rate · number

Sampling rate in Hz. Positive value up to 1,000,000.

context · object

Optional JSON context for the decoding session. Include session_history (array of prior intents or selected letters) for multi-turn spelling or sentence completion. Must serialize to at most 16,000 characters.

output · object

Show output fields

output.locale · string

BCP-47 locale code. Between 2 and 32 characters.

output.format · string

"report" or "json". Defaults to "json".

output.include_diagnostics · boolean

Include per-step timing and routing in the completed job payload. Defaults to false.

Response

Returns 202 Accepted. An optional Idempotency-Key header is supported; scope is neuro_decode.

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

Add include=diagnostics to inspect routing fallbacks and MetaBCI step timing.

Completed job output

decoded_intent · string

The primary decoded intent, e.g. "move_left", "select_row_3", "letter_H".

confidence · number

Confidence score for decoded_intent between 0 and 1.

paradigm_detected · string

The paradigm classification applied during decoding.

predicted_text · string

Optional sentence completion or phrase acceleration text (mind-to-speech use case).

alternatives · array

Ranked alternative intents. Each item includes intent and confidence.

session_context · string

Summary of multi-turn session state echoed back to the client for context continuity.

seizure_detected · boolean | null

Seizure flag from the MetaBCI sidecar when configured. null when the sidecar is unavailable.

red_flags · array

Warning signals that should surface in your UI or trigger a safety interlock.

disclaimer · string

Mandatory probabilistic disclaimer text.

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 }
  ],
  "session_context": "User navigating; last intents favor left corridor.",
  "seizure_detected": false,
  "red_flags": [],
  "disclaimer": "BCI outputs are probabilistic..."
}

Use cases

Thought-to-action (smart home / wheelchair)

Set paradigm to "motor_imagery". Map decoded_intent values to your action layer (MQTT topics, ROS commands, smart home scenes). Use alternatives to power confidence UI.

Mind-to-spelling / P300

Set paradigm to "p300". Pass the running letter sequence in context.session_history. decoded_intent returns the selected symbol; predicted_text accelerates phrase completion.

SSVEP target selection

Set paradigm to "ssvep". decoded_intent returns the target id or frequency label; use alternatives to highlight competing UI targets.

Error codes

Code	HTTP	Description
neuro_decode_disabled	403	NEURO_DECODE_ENABLED=false in server environment
invalid_request_body	400	Schema validation failed
job_create_failed	500	Database insert failed
job_trigger_failed	502	Background worker not reachable