Platform SDK

What is the Platform API?

You distribute the Focus+ band and own the product experience. Brain-Life runs the signal processing, the models, and the analytics behind them — reachable through one REST API and one WebSocket.

Your application reads raw ADC samples off the band over Bluetooth and pushes them to us. We filter, extract features, run the classifiers, and push results back per second. You never implement signal processing, and you never train a model.

This page refers to Platform API v1 and BLE protocol v2.0 (firmware v0.4.0).

How integration works

Your end users never create a Brain-Life account. You identify them with an external_user_id — any opaque string you choose. We store no name, no email, nothing that identifies a person.

This is deliberate rather than a simplification. Holding no personal data for your users means the legal obligation sits where the actual relationship is: with you.

Each band you receive is registered to your organization. A band that has not been assigned cannot send data — this stops a unit lost in shipping, or resold on the grey market, from consuming platform resources on your account.

Before you begin

Three things, all issued by your Brain-Life contact:

Quickstart

The complete integration is four calls. Everything after this section is detail.

POST /v1/sessions
Authorization: Bearer bl_sk_…

{
  "external_user_id": "partner-user-12345",
  "device_id": "dev_a71f…",
  "metadata": { "program": "focus-training-week-3" }
}

→ {
  "session_id": "ses_3f9c…",
  "ticket": "rt_a91f…",
  "expires_in": 60
}

wss://api.brainlife.tech/v1/realtime?token=rt_a91f…

POST /v1/sessions/ses_3f9c…/end

metadata is free space for your own context — which exercise, which week. We store it and return it untouched. The same rule applies: no personal data.

API keys & tickets

There are two credentials, and the distinction matters.

Your API key authenticates REST calls through an Authorization header. It never appears in a URL.

Browsers cannot set headers on a WebSocket, so the realtime token travels in the query string — where it is written to the access log of every proxy along the path. That is precisely why it is a 60-second single-use ticket rather than your key: even if logged, it is worthless moments later.

POST /v1/realtime/ticket        # for reconnects
Authorization: Bearer bl_sk_…

→ { "ticket": "rt_a91f…", "expires_in": 60 }

Scopes

Session lifecycle

A session is one continuous recording for one end user. Every sample belongs to exactly one session.

Calling /end explicitly is recommended but not required — dropped connections are ordinary, and the system does not depend on a clean shutdown.

Sending signal

{
  "type": "signal",
  "session_id": "ses_3f9c…",
  "timestamp": 1785312000123,
  "eeg": {
    "AF3": [4102, 4098, 4110, 4105],
    "AF4": [4088, 4091, 4085, 4093]
  },
  "ppg": [2048, 2051, 2049, 2047],
  "sample_rate": 128
}

Channel names follow the international 10-20 convention, so existing EEG tooling reads them without translation.

Receiving results

The connection is bidirectional. These messages travel server to client.

Focus

{
  "type": "focus",
  "state": "focused",          // focused | relaxed | neutral
  "confidence": 0.87,          // 0.0 – 1.0
  "session_id": "ses_3f9c…",
  "external_user_id": "partner-user-12345",
  "timestamp": 1785312000456
}

Power bands

Emitted once per second.

{
  "type": "powerbands",
  "channels": {
    "AF3": { "delta": 12.4, "theta": 8.1, "alpha": 15.7, "beta": 9.2, "gamma": 3.1 },
    "AF4": { "delta": 11.8, "theta": 7.9, "alpha": 16.2, "beta": 8.8, "gamma": 2.9 }
  },
  "unit": "uV^2/Hz",
  "timestamp": 1785312000123
}

Device state

{
  "type": "device",
  "connected": true,
  "contact_quality": { "AF3": "good", "AF4": "poor" },
  "battery": 0.72
}

BLE protocol

Connect over GATT and subscribe to the streaming characteristics, then send the start command. Subscribing after the device has begun streaming loses whatever it emitted in between.

Brainlife Streaming Service

Service UUID 82e0d5f0-9462-4867-8bf3-70c9aea8e878

Sensor Control sends configuration commands to the EPC chips and reads their configuration back. EPC Control starts and stops acquisition:

Full GATT service map

Device Information Service

All characteristics are READ-only UTF-8 strings, except PnP ID.

Battery & charge state

The standard Battery Service (0x180F) exposes two characteristics. Most integrations read only the first and miss the one that actually explains what the battery is doing.

Battery Level — 0x2A19

READ and NOTIFY. One byte, uint8, charge level 0–100%.

Battery Level Status — 0x2BED

READ and NOTIFY. Three bytes: one flags byte followed by a 16-bit Power State field.

Byte 0 — Status Flags. Indicates which fields are present.

Bytes 1–2 — Power State. This is where charge behaviour lives.

Both characteristics support NOTIFY, so subscribe rather than poll.

Packet format

Every data point is ten bytes.

The header identifies the channel, the tail is always 0x0A, and the payload is a little-endian signed integer of raw ADC counts.

One streaming packet carries 21 data points — 210 bytes.

LED & haptics

The Brainlife Control Service (80896cd0-8a11-4967-a419-66e4316e22b2) drives the on-device LED and vibration motor. Both are available in customer firmware.

LED

Characteristic 80896cd1-…, one byte: 0x00 red, 0x01 green, 0x02 off.

Vibration motor

Characteristic 80896cd2-…, four bytes — state, duty cycle 1–100, then duration as a little-endian uint16 in milliseconds (1–60000).

on, 50% duty, 1000 ms   →  01 32 E8 03
on, 100% duty, 5000 ms  →  01 64 88 13
off                     →  00 00 00 00

When the state byte is 0x00 the device stops immediately and ignores the remaining three bytes.

Services you will not see

The Factory Service (810fb410-b52d-4c48-b94e-3396e1c73e73) provides diagnostics and provisioning — reading and writing device internals such as MAC address and serial number, and a ship-mode command that powers the unit down. It is exposed only in factory firmware and is removed from customer units. If your discovery code finds it, you are holding a factory device and should not ship against it.

The SMP Service (8d53dc1d-1db7-4cd3-868b-8a527460aa84) carries pairing, bonding, encryption, and secured OTA. Your BLE stack drives it; you do not write to it directly.

Rate limits & quota

Every limit is scoped to your organization, never global, so another partner's traffic spike cannot exhaust your capacity. You also hold a reserved minimum that stays available under platform-wide load.

Realtime usage is metered by connection time, not message count. A 30-minute session produces roughly 1,800 messages regardless of what you do — the device sets that rate, so charging per message would penalize normal use.

At 80% of quota we send a quota.threshold webhook. You should never discover a limit by having your service stop.

Webhooks

For events that suit neither the socket nor polling.

Every delivery is signed with HMAC-SHA256 using a secret unique to your organization:

X-BrainLife-Timestamp: 1785312000
X-BrainLife-Signature: sha256=<HMAC(secret, "1785312000." + body)>

Store the event_ids you have processed and skip duplicates. A retry can redeliver an event whose acknowledgement was lost in transit, so duplicates are ordinary traffic rather than a sign of attack. Failed deliveries retry with exponential backoff for 24 hours.

Data retention

Raw signal is thousands of times larger than summary data while its usefulness drops sharply within days. If you need it longer, download it inside the 30-day window through the raw endpoint — which puts the data somewhere you fully control — or ask about extended storage.

A data.expiring webhook fires seven days ahead, so nothing disappears unannounced.

Demo app

A complete working integration in Python: BLE transport, protocol parsing, session lifecycle, and the realtime connection in roughly 600 lines. Written to be read — start in main.py and the whole flow is there top to bottom.

Package structure

Running it

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

export BRAINLIFE_API_KEY=bl_sk_your_key_here
python -m brainlife_demo.main --simulate

With a band in hand:

python -m brainlife_demo.main --scan
python -m brainlife_demo.main --address <ADDR>

Expected output:

INFO  device Brainlife Focus+ fw=v0.4.0 battery=72%
INFO  session ses_3f9c… started

  focus    focused    0.87 |##########################    |
  bands    AF3  delta=  12.4 theta=   8.1 alpha=  15.7
  device   connected=True battery=72%  POOR CONTACT: AF4

Requires Python 3.10 or newer, on macOS 11+, Windows 10+, or Linux with BlueZ 5.55+.

Request repository access →

Integration FAQs

Why is my message quota exhausted so quickly?

Almost always one message per sample. At 128 Hz that is 128 messages per second per user. Batch 0.25–1 second into each message.

Classification looks wrong, but my signal looks clean

Check whether you are filtering before sending. Our engine expects raw ADC counts and applies its own filtering; a second chain in front of it skews results in ways that are very hard to trace.

Why was my session_id rejected?

Session ids are server-issued. Take the one returned by POST /v1/sessions and use it unchanged.

The user's signal went flat — are they relaxed?

Unknown without contact_quality from the device message. A detached electrode and a calm user produce the same trace.

My connection drops every few hours

Expected. Maximum connection lifetime is 8 hours by design. Fetch a new ticket and reconnect with backoff.

Should I retry after a close code?

Only for 1000, 4001, 4002, 4008, and 4009. The rest are configuration errors that will never succeed on retry.

Can I use my own analysis instead of yours?

Yes — the raw endpoint gives you back everything your devices produced. Many research partners do exactly this.

Support

Reach your Brain-Life technical contact for repository access, environment URLs, key rotation, quota changes, or device registration.

When reporting an integration problem, include your organization_id, the session_id, and the timestamp range. Do not include raw signal data or anything identifying an end user.