REST API Reference — v1

Base URL: https://api.neurodkx.com/v1. All requests require an Authorization: Bearer <api_key> header. Responses are JSON. Rate limit: 120 requests/minute per key.

POST /sessions

Create a new decode session. Returns a session ID used in subsequent requests.

Request body

POST /v1/sessions

// Request
{
  "channels": 16,
  "srate": 500,
  "classes": ["left_hand", "right_hand"],
  "alignment": true,
  "calibration_ref": "cal_patient_001_s1"  // optional
}

// Response 201 Created
{
  "session_id": "ses_8fQzNxKj3Av",
  "status": "ready",
  "created_at": "2026-03-14T10:22:08Z",
  "alignment_applied": true,
  "pipeline_version": "0.9.2"
}

POST /decode

Submit a batch of EEG epochs for offline decoding. EEG data as base64-encoded float32 array, shape [n_epochs, n_channels, n_samples].

POST /v1/decode

// Request
{
  "session_id": "ses_8fQzNxKj3Av",
  "eeg_data": "<base64 float32 array>",
  "shape": [10, 16, 2000],  // [epochs, channels, samples]
  "timestamps": [...]  // optional epoch onset times
}

// Response 200 OK
{
  "decode_id": "dec_7HxPqBvM1Zw",
  "results": [
    { "epoch": 0, "label": "left_hand",  "confidence": 0.91, "latency_ms": 72 },
    { "epoch": 1, "label": "right_hand", "confidence": 0.87, "latency_ms": 68 }
  ],
  "mean_confidence": 0.89,
  "processing_time_ms": 340
}

GET /sessions/{session_id}/status

Poll the status of a session or a long-running batch decode job.

GET /v1/sessions/ses_8fQzNxKj3Av/status

// Response 200 OK
{
  "session_id": "ses_8fQzNxKj3Av",
  "status": "active",  // ready | active | completed | error
  "epochs_decoded": 148,
  "mean_latency_ms": 71.4,
  "mean_confidence": 0.88,
  "artifact_reject_rate": 0.04,
  "uptime_s": 1824
}

GET /health

Service health check. Returns 200 when all pipeline services are available.

GET /v1/health

// Response 200 OK
{
  "status": "healthy",
  "version": "0.9.2",
  "pipeline": "ok",
  "classifier": "ok",
  "timestamp": "2026-03-14T10:24:00Z"
}

Error codes

All error responses follow the format {"error": {"code": "...", "message": "..."}}.

400 bad_request — invalid shape, missing fields, unsupported srate
401 unauthorized — missing or invalid API key
404 session_not_found — session_id does not exist or expired
422 unprocessable — EEG data too noisy to decode (artifact rate >60%)
429 rate_limited — exceeded 120 requests/min
503 service_unavailable — pipeline maintenance or overload