Event Streaming (SSE)

Live activity feed

GET /api/v1/events streams your helper’s activity in real time over SSE (Server-Sent Events, a simple one-way HTTP stream). Use it to:

• Watch helper activity from an external dashboard
• Log actions to your own systems
• Trigger follow-on automation when specific events happen

This is a read-only feed. It mirrors the same activity you see in the dashboard’s Work Ledger.

Connecting

curl -N https://app.brainroad.com/api/v1/events \
  -H "Authorization: Bearer brk_your_key_here"

The -N flag disables curl’s buffering so events appear immediately.

Authentication uses an API key with the activity:read scope. If no helper is provisioned yet, the endpoint returns 404.

Event format

event: connected
data: {"agentIds":["abc123"],"message":"Subscribed to events"}

event: activity
data: {"id":42,"agentId":"abc123","eventType":"email.ingest","category":"communication","status":"completed","title":"Inbound email mirrored to Brain","detail":{...},"triageCardId":null,"costTokens":null,"costUsd":null,"source":"webhook","createdAt":"2026-07-20T12:00:00.000Z","resolvedAt":null,"resolvedBy":null}

The first frame is always connected and lists the helper IDs you are subscribed to (one per runtime you run). Every later frame is activity.

Activity fields

Field	Type	Description
id	number	Event ID
agentId	string	Which helper emitted it
eventType	string	Specific event type
category	string	One of the categories below
status	string	Event status, for example completed or failed
title	string	Human-readable summary
detail	object/null	Event-specific data
triageCardId	string/null	Link to the review card this event belongs to, when there is one
costTokens / costUsd	number/null	Usage cost, when applicable
source	string	Where the event originated
createdAt	string	ISO 8601 timestamp
resolvedAt / resolvedBy	string/null	Resolution info for events that needed one

Filtering by category

curl -N "https://app.brainroad.com/api/v1/events?category=communication" \
  -H "Authorization: Bearer brk_your_key_here"

Categories: lifecycle, communication, tool_use, coding, social, config, error.

Keepalive and revocation

• The server sends a : keepalive comment every 30 seconds. SSE client libraries handle these automatically.
• The server re-checks your key roughly every 30 seconds. If the key is revoked, or its status cannot be verified, the stream sends a final event: revoked frame and closes. Reconnecting requires a valid key.

Example: Python

import json
import sseclient  # pip install sseclient-py
import requests

response = requests.get(
    "https://app.brainroad.com/api/v1/events",
    headers={"Authorization": "Bearer brk_your_key_here"},
    stream=True,
)

client = sseclient.SSEClient(response)
for event in client.events():
    if event.event == "connected":
        print("Connected:", json.loads(event.data))
    elif event.event == "activity":
        data = json.loads(event.data)
        print(f"[{data['category']}] {data['title']}")

Example: Node.js

import EventSource from "eventsource";

const es = new EventSource("https://app.brainroad.com/api/v1/events", {
  headers: { Authorization: "Bearer brk_your_key_here" },
});

es.addEventListener("connected", (e) => console.log("Subscribed:", JSON.parse(e.data)));
es.addEventListener("activity", (e) => {
  const data = JSON.parse(e.data);
  console.log(`[${data.category}] ${data.title}`);
});
es.onerror = () => console.log("Connection lost, reconnecting...");