Neural OS API

The Neural OS API provides a unified interface for accessing brain-computer interface data across multiple hardware devices. Decode raw neural signals into actionable cognitive metrics with a single API call.

Endpoint Status:

DESIGNSpec complete

ALPHAInternal testing

LIVEProduction

Hardware Agnostic

One API for 6+ BCI devices. No hardware-specific code needed.

Real-time Decoding

Sub-5ms latency from raw EEG to cognitive state output.

Privacy by Design

Raw neural data never leaves the device. Only decoded metrics are transmitted.

Quick Start

Install the SDK

python

pip install neural-os

Connect & Stream

python

import neural_os
# Initialize client
client = neural_os.Client(api_key="nos_sk_...")
# Connect to any BCI device (auto-detected)
device = client.devices.connect()
print(f"Connected: {device.name} ({device.channels}ch)")
# Start real-time cognitive state streaming
async for state in client.stream.decode():
    print(f"Attention: {state.attention:.2f}")
    print(f"Cognitive Load: {state.cognitive_load:.2f}")
    print(f"Flow State: {state.flow_state:.2f}")
    
    # React to neural events
    for event in state.events:
        if event.type == "focus_spike":
            print("Peak focus detected!")
        elif event.type == "drowsiness_onset":
            print("User getting tired, suggest break")

JavaScript / Node.js

javascript

import { NeuralOS } from 'neural-os';
const client = new NeuralOS({ apiKey: 'nos_sk_...' });
// Connect to device
const device = await client.devices.connect();
console.log(`Connected: ${device.name}`);
// Subscribe to decoded states
client.stream.decode().subscribe({
  onState: (state) => {
    console.log('Attention:', state.attention);
    console.log('Flow:', state.flowState);
  },
  onEvent: (event) => {
    if (event.type === 'cognitive_shift') {
      adaptContent(event.data);
    }
  }
});

cURL

bash

# Get current cognitive state
curl -X GET https://api.neural-os.dev/v1/stream/decode \
  -H "Authorization: Bearer nos_sk_..." \
  -H "Content-Type: application/json"
# Response
{
  "timestamp": "2026-02-24T10:30:00Z",
  "session_id": "nos_sess_7f3a2b1e",
  "device": {
    "name": "OpenBCI Cyton",
    "channels": 8,
    "sample_rate": 250
  },
  "signal_quality": 0.952,
  "decoded_states": {
    "attention": 0.847,
    "relaxation": 0.423,
    "cognitive_load": 0.612,
    "emotional_valence": 0.315,
    "fatigue_index": 0.189,
    "flow_state": 0.721
  },
  "frequency_bands": {
    "delta": 2.34,
    "theta": 5.67,
    "alpha": 10.23,
    "beta": 22.45,
    "gamma": 38.91
  },
  "events": [
    { "type": "focus_spike", "confidence": 0.94 }
  ]
}