Sister Song publishes AI commentary and bets from each strategy (an AI persona), with its live results, and match data: status and scores, events, text commentary, pressure and live odds. Staying up to date explains how we announce changes, and the glossary explains the terms.
How it works
- Find a match.
GET /lists the matches being streamed. A fixture'sfixtures/ live idis thematch_you stream.id - Open a stream. Over SSE, one HTTP request per match and language. Over a WebSocket, one connection for any number of matches.
- Get the replay, then live messages. Every stream starts with a replay of everything already published for the match, then sends each new message as it's published.
Quick start
The examples use FC Barcelona vs Real Madrid (match_ 19732648, 25 October 2026), shortened in places.
-
Get your token and strategy IDs. Sign in at song.brainanalytics.co. Once Brain Analytics has linked your account to your client, this step shows your token and the IDs of the strategies you can stream. Settings shows the token too. Strategy IDs are short text IDs, such as
sister-.song- v1 Your details
-
Find a match. Call
GET /, orfixtures/ live GET /before kick-off. A fixture'sfixtures/ upcoming idis thematch_you stream.id curl -H "X-Token: YOUR_TOKEN" https://publisher.prod.song.brainanalytics.co/fixtures/liveconst response = await fetch("https://publisher.prod.song.brainanalytics.co/fixtures/live", { headers: { "X-Token": "YOUR_TOKEN" }, }); const { fixtures } = await response.json();import httpx response = httpx.get( "https://publisher.prod.song.brainanalytics.co/fixtures/live", headers={"X-Token": "YOUR_TOKEN"}, ) fixtures = response.json()["fixtures"] -
Open a stream. SSE is the simplest option: one HTTP request per match.
curl -N -H "X-Token: YOUR_TOKEN" "https://publisher.prod.song.brainanalytics.co/sse?match_id=19732648&topics=ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status&language=en"const url = new URL("https://publisher.prod.song.brainanalytics.co/sse"); url.searchParams.set("match_id", "19732648"); url.searchParams.set("topics", "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status"); url.searchParams.set("language", "en"); url.searchParams.set("token", "YOUR_TOKEN"); // a browser's EventSource can't send headers const seen = new Set(); function handle(msg) { if (msg.seq) { // The end of a replay can repeat the first live messages. const key = `${msg.match_id}|${msg.topic}|${msg.language}|${msg.seq}`; if (seen.has(key)) return; seen.add(key); } show(msg.publish_type, msg.data); } let delay = 1000; function connect() { const source = new EventSource(url); source.onmessage = (event) => { delay = 1000; const frame = JSON.parse(event.data); if (frame.publish_type !== "snapshot") return handle(frame); if (frame.chunk === 1) { seen.clear(); clearMatch(); // a new replay is starting } frame.messages.forEach(handle); }; source.onerror = () => { // EventSource reconnects by itself, except after an HTTP error such as a 502 during a deploy. if (source.readyState !== EventSource.CLOSED) return; setTimeout(connect, delay); delay = Math.min(delay * 2, 30000); }; } connect();import json import httpx params = { "match_id": 19732648, "topics": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status", "language": "en", } seen = set() def handle(msg): if msg.get("seq"): # The end of a replay can repeat the first live messages. key = (msg["match_id"], msg["topic"], msg["language"], msg["seq"]) if key in seen: return seen.add(key) print(msg["publish_type"], msg["data"]) # The server sends ": ping" after 15 quiet seconds, so a minute of silence means the connection is gone. with httpx.stream( "GET", "https://publisher.prod.song.brainanalytics.co/sse", params=params, headers={"X-Token": "YOUR_TOKEN"}, timeout=httpx.Timeout(10, read=60), ) as response: response.raise_for_status() for line in response.iter_lines(): if not line.startswith("data: "): continue # ": ok", ": ping" and the blank lines between frames frame = json.loads(line[len("data: "):]) if frame["publish_type"] != "snapshot": handle(frame) continue if frame["chunk"] == 1: seen.clear() # a new replay is starting for msg in frame["messages"]: handle(msg)Tip
Want to see the stream before writing any code? Try it live replays this match in your browser, with your token.
-
Read the replay, then live messages. The stream starts with
snapshotframes that replay everything already published for the match. After that, you get each new message as it's published. The samples drop the duplicates where the two meet, and start over when a new replay begins (chunk: 1).showandclearMatchstand for your own rendering code.
Before you go live
Check that your client:
- Drops duplicates on
(match_. The end of a replay can repeat the first live messages. See Duplicates and gaps.id, topic, language, seq) - Starts over on
chunk: 1. Every connection, and every WebSocketsubscribe, begins with a fresh replay. See Replay frames. - Reconnects. Over SSE, reconnect yourself with a backoff after an HTTP error, such as a
502during a deploy. Over a WebSocket, send{"command": "ping"}at least every 30 seconds. See Reconnecting and Keeping the connection alive. - Orders each stream by
seq, not by minute. AI minutes hold still through half-time and can step back at full time. See Ordering. - Doesn't assume clocks only go up. The period clocks in
match_can jump ahead or back. See Periods.status - Copes without pressure. Some competitions, currently including the UEFA Champions League, have no
pressuremessages. Seepressure. - Keeps what it has shown. We never withdraw a message: a reworded commentary line arrives again, and a disallowed goal is followed by a
VARevent. Seeevent. - Flips the handicap sign on older bets. Bet slips and tips without
handicap_carry the opposite sign on handicap markets. See Bet slips.is_ line: true - Stores IDs as 64-bit integers.
bet_,id wager_and others already exceed 32 bits.selection_ id - Ignores what it doesn't recognise. We add fields, message types, topics and values without notice. See Staying up to date.
Environments
| Production | Staging | |
|---|---|---|
| HTTP and SSE | https:// | https:// |
| WebSocket | wss:// | wss:// |
Each environment has its own token. To see the other one, switch environment in the portal: in Settings, or in Your details in the Quick start. Staging runs the same API but covers fewer competitions, so it has fewer matches.
Authentication
Every request except GET / needs your client token. The Quick start says where to find it. Send it in one of two ways:
- Header
X-, for server-side clients.Token: YOUR_ TOKEN - Query string
?token=YOUR_, for browsers. The browserTOKEN EventSourceandWebSocketAPIs can't set headers.
If you send both, the header wins. A missing, unknown or disabled token gets HTTP 403. A WebSocket with a bad token is refused during the handshake, also with 403.
The API accepts cross-origin requests, so browser apps can call it directly.
Topics and languages
A stream is identified by three things: the match (match_), the topic and the language.
| Topic | Message type | Per language | Content | Sent |
|---|---|---|---|---|
ai- | ai_ | yes | The strategy's commentary and the bets it places | when the strategy acts, every few minutes |
ai- | ai_ | no | The strategy's bets so far and its profit and loss | about once a minute |
match_ | match_ | yes | Text commentary from our data provider (not AI) | as lines are written |
event | event | no | Goals, cards, substitutions, VAR reviews and penalties | as they happen |
match_ | match_ | no | Match state, scores, periods and clock | about once a minute |
pressure | pressure | no | Each team's pressure, minute by minute | every minute: one message per team |
odds | odds | no | All live odds markets, in IM's format | when the odds change |
{strategy_ is the strategy's ID, so the Sister Song strategy's topics are ai- and ai-. A strategy can be limited to certain competitions. Its topics stay empty for matches outside them.
Languages: en (default), zh, vi and th.
- Per-language topics are published once in each language. English goes out first and the translations usually follow within a few seconds. All copies of an item share the same
data., so you can use it to match translations.id - The other topics are published once, with
language: "all". They're the same whichever language you choose.
When matches stream: messages start about 15 minutes before kick-off and stop about 30 minutes after full time. You can subscribe earlier. The stream stays empty until the first message.
HTTP endpoints
| Endpoint | Response |
|---|---|
GET / | {"fixtures": [LiveFixture]}: matches on the live list. Updated twice a minute. |
GET / | {"fixtures": [Fixture]}: matches kicking off in the next 3 days, soonest first. |
GET / | {"mappings": [{"fixture_: each fixture's IM event_, for fixtures from yesterday to 14 days ahead. |
GET / | {"tips": [Tip]}: the strategies' bets, written up as tips. See Tips. |
GET / | {"status": "ok"}. No token needed. |
The live list holds matches in play, plus matches about to kick off (from about 15 minutes before) or just finished. Use state_ to tell them apart.
Both fixture lists show only the matches Sister Song streams. Add ?all=true to also see matches we don't stream.
Fixture, competition, team and event type IDs come from our data provider, Sportmonks. IM's IDs are separate: event_ here, and the IM IDs in odds messages and bet slips. The fixture_ and event_ in the mapping are both integers.
If fixture data is briefly unavailable, the fixture endpoints return 502. Retry after a few seconds.
LiveFixture
idinteger- Fixture ID: use it as
match_id sport_integerid - Always
1(football) league_integerid - Competition ID
namestring- For example
"FC Barcelona vs Real Madrid". It can be"". state_,id state_integer, stringname - Match state, for example
22/"INPLAY_. See state codes. A state we don't know yet is named2ND_ HALF" "STATE_.<id>" starting_stringat - Kick-off in UTC, for example
"2026-10-25T20:00:00" fixture_booleanwhitelisted truewhen the match was added on its own rather than through its competition. Every strategy covers such matches. Alwaysfalsewith?all=true.
Fixture (upcoming)
idinteger- Fixture ID: use it as
match_id sport_integerid - Always
1(football) starting_stringat - Kick-off in UTC
league_,id league_integer, stringname - Competition
season_,id season_integer, stringname - Season
stage_,id stage_integer, stringname - Stage, for example
"Regular Season" round_,id round_integer, stringname - Round
state_integerid - Always
1(not started) home_,team_ id away_integerteam_ id - Team IDs
home_,team_ name away_stringteam_ name - Team names
result_stringinfo - Empty (
"") before the match
Missing names are empty strings and missing IDs are 0.
Streaming over SSE
One SSE stream carries one match in one language. Open another stream for another match or language.
GET https://publisher.prod.song.brainanalytics.co/sse?match_id=19732648&topics=ai-commentary-sister-song-v1,event,pressure&language=en HTTP/1.1
X-Token: YOUR_TOKENmatch_integerRequiredid - The fixture ID
topicsstringRequired- Comma-separated (
topics=a,b) or repeated (topics=a&topics=b) languagestringen(default),zh,viorth. It applies to per-language topics. The other topics always arrive, and withallonly they arrive.tokenstring- Your token, if you can't send the
X-headerToken
The stream sends, in this order:
: ok(an SSE comment) as soon as you connect.- One or more
snapshotframes: the replay (see Replay frames). - Live messages, each on its own
data:line. - A
: pingcomment whenever 15 seconds pass with no messages, to keep the connection open.
Every frame is a default message event, with no event: or id: field. Read publish_ to tell frames apart: it's "snapshot" for replay frames and the message type for everything else.
A live message:
{
"timestamp": "2026-10-25T20:26:01.112723",
"seq": 45,
"topic": "pressure",
"match_id": 19732648,
"language": "all",
"publish_type": "pressure",
"data": { "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" },
"id": null
}timestampstring- When the message was published, in UTC (see Times)
seqinteger or null- The message's position in its stream (see Duplicates and gaps)
topicstring- The topic
match_integerid - The fixture ID
languagestringen,zh,viorth, orallon the topics that aren't per languagepublish_stringtype - The message type, such as
pressure(see Message reference) dataobject- The message
idnull- Always
nullon live messages. Messages inside a replay carry their storedidandcreated_.at
Errors. 400 if topics is missing, 422 if match_ is missing or a parameter is invalid, and 403 for a bad token.
Reconnecting
- The server ends your stream if you fall more than 256 messages behind. Streams also end when the service restarts, for example during a deploy.
- A browser's
EventSourcereconnects by itself after a dropped connection. After an HTTP error response, such as502during a deploy, it stops for good, so reconnect yourself with a backoff, as the Quick start sample does. - Every new connection starts with a fresh replay.
Streaming over WebSocket
One WebSocket can hold many subscriptions: several matches, topics and languages. All messages are JSON text, in both directions.
Connect to wss://, or send the X- header instead if your WebSocket library can.
Commands
| Command | Fields | Reply |
|---|---|---|
subscribe | topic, match_, language (default en) | One ack per topic with status: "subscribed", then the replay frames |
unsubscribe | topic, match_, language (default en) | One ack per topic with status: "unsubscribed" |
unsubscribe_ | match_ | One ack with status: "unsubscribed_ |
unsubscribe_ | none | One ack with status: "unsubscribed_ |
ping | none | {"type": "pong"} |
commandstring- One of the commands above. Others get no reply.
topicstring or array of string- One topic, a comma-separated string or a JSON array. Needed by
subscribeandunsubscribe. match_integerid - The fixture ID. Needed by every command except
unsubscribe_andall ping. languagestringen(default),zh,viorth, as on SSE.allsubscribes to the topics that aren't per language only.
The replay after a subscribe covers all the topics in that command. language works as it does on SSE. It sets the language of the per-language topics, and the other topics arrive whatever language you send. So one command covers a whole match:
{ "command": "subscribe", "topic": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_commentary,event,match_status,pressure,odds", "match_id": 19732648, "language": "en" }To unsubscribe, send the same topics and language.
An ack:
{
"type": "ack",
"timestamp": "2026-10-25T21:40:00.123456",
"match_id": 19732648,
"language": "en",
"topic": "ai-commentary-sister-song-v1",
"status": "subscribed",
"error": null
}typestring- Always
"ack" timestampstring- When it was sent, in UTC
match_integer or nullid - The command's fixture ID
languagestring or null- The command's language
topicstring or null- One topic from the command
statusstringsubscribed,unsubscribed,unsubscribed_,all_ by_ match_ id unsubscribed_orall errorerrorstring or null- What was wrong with the command, when
statusiserror
Subscribing again to something you already hold is harmless. You get a new ack and a fresh replay.
Live messages
{
"type": "pressure",
"timestamp": "2026-10-25T20:26:01.112723",
"match_id": 19732648,
"language": "all",
"topic": "pressure",
"seq": 45,
"data": { "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" }
}Live WebSocket messages have the same fields as live SSE messages, except that they give their type in type and have no id. Messages inside replay frames use publish_, as on SSE.
Keeping the connection alive
If the server receives nothing from you for 60 seconds, it drops every subscription on that connection and sends:
{ "type": "unsubscribed", "reason": "timeout" }The socket stays open, but you have to subscribe again.
Important
Send {"command": "ping"} every 30 seconds. WebSocket ping frames, which many libraries send by themselves, don't count: only a message from you resets the timer.
Errors
A command with no topic or match_, or with an unknown language, gets an error ack:
{ "type": "ack", "timestamp": "2026-10-25T21:40:00.123456", "match_id": 19732648, "language": null, "topic": null, "status": "error", "error": "Missing topic or match_id" }Unknown commands get no reply. A frame that isn't a JSON object closes the connection.
Example client
const socket = new WebSocket("wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN");
const subscribe = {
command: "subscribe",
topic: "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
match_id: 19732648,
language: "en",
};
const seen = new Set();
let pinger;
function handle(msg, type) {
if (msg.seq) {
const key = `${msg.match_id}|${msg.topic}|${msg.language}|${msg.seq}`;
if (seen.has(key)) return;
seen.add(key);
}
show(type, msg.data);
}
socket.onopen = () => {
socket.send(JSON.stringify(subscribe));
pinger = setInterval(() => socket.send(JSON.stringify({ command: "ping" })), 30000);
};
socket.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "ack":
case "pong":
return;
case "unsubscribed": // nothing heard from us for 60 seconds
return socket.send(JSON.stringify(subscribe));
case "snapshot":
if (msg.chunk === 1) {
seen.clear();
clearMatch(); // a new replay is starting
}
return msg.messages.forEach((item) => handle(item, item.publish_type));
default:
return handle(msg, msg.type);
}
};
socket.onclose = () => clearInterval(pinger); // then reconnect, with a backoffimport asyncio
import json
import websockets
URL = "wss://publisher.prod.song.brainanalytics.co/ws?token=YOUR_TOKEN"
SUBSCRIBE = {
"command": "subscribe",
"topic": "ai-commentary-sister-song-v1,ai-results-sister-song-v1,match_status",
"match_id": 19732648,
"language": "en",
}
seen = set()
def handle(msg, kind):
if msg.get("seq"):
key = (msg["match_id"], msg["topic"], msg["language"], msg["seq"])
if key in seen:
return
seen.add(key)
print(kind, msg["data"])
async def keep_alive(socket):
# The library's own WebSocket pings don't reset the server's 60-second timer. This does.
while True:
await asyncio.sleep(30)
await socket.send(json.dumps({"command": "ping"}))
async def main():
# Replay frames of odds can pass the library's default 1 MB message limit.
async with websockets.connect(URL, max_size=None) as socket:
await socket.send(json.dumps(SUBSCRIBE))
pinger = asyncio.create_task(keep_alive(socket))
try:
async for raw in socket:
msg = json.loads(raw)
if msg["type"] in ("ack", "pong"):
continue
if msg["type"] == "unsubscribed": # nothing heard from us for 60 seconds
await socket.send(json.dumps(SUBSCRIBE))
elif msg["type"] == "snapshot":
if msg["chunk"] == 1:
seen.clear() # a new replay is starting
for item in msg["messages"]:
handle(item, item["publish_type"])
else:
handle(msg, msg["type"])
finally:
pinger.cancel()
asyncio.run(main())Session overview
sequenceDiagram
accTitle: A WebSocket session
autonumber
participant C as Your app
participant P as Publisher
C->>P: GET /fixtures/live (X-Token)
P-->>C: 200 {fixtures: [...]}
C->>P: WebSocket /ws?token=...
P-->>C: connection accepted
C->>P: subscribe ai-commentary-sister-song-v1,ai-results-sister-song-v1,event,... (language "en")
P-->>C: one ack per topic, then snapshot frames 1..n
loop every 30 s
C->>P: {command: "ping"}
P-->>C: {type: "pong"}
end
P-->>C: live messages: ai_commentary, ai_results, match_commentary, event, match_status, pressure, oddsReplays, ordering and duplicates
Replay frames
When you connect over SSE, or subscribe over a WebSocket, you first get a replay. It holds every message already published for that match and those topics, oldest first, split into frames of up to 30 messages. You always get at least one frame. If nothing has been published yet, its messages list is empty.
{
"type": "snapshot",
"publish_type": "snapshot",
"timestamp": "2026-10-25T21:40:00.512345",
"match_id": 19732648,
"language": "en",
"topics": ["ai-commentary-sister-song-v1", "pressure"],
"chunk": 1,
"total_chunks": 8,
"messages": [
{
"id": 1940582,
"created_at": "2026-10-25T19:46:11.147292Z",
"timestamp": "2026-10-25T19:46:11.127134Z",
"seq": 1,
"topic": "ai-commentary-sister-song-v1",
"match_id": 19732648,
"language": "en",
"publish_type": "ai_commentary",
"data": {
"id": "5792b134-ee1d-456d-89ec-271db69a88bd",
"minute": 0,
"period_id": 0,
"period_name": "Not Started",
"commentary": "Welcome everyone to our stream, let's analyze this massive El Clásico together and find some smart investments!",
"action_type": "welcome",
"bet_slips": []
}
}
]
}type,publish_stringtype - Both
"snapshot" timestampstring- When the frame was built, in UTC
match_integerid - The fixture ID
languagestring- The language you asked for
topicsarray of string- The topics replayed, in any order
chunk,total_integerchunks - This frame's number, from 1, and how many frames the replay has
messagesarray of object- Up to 30 messages, oldest first. They have the fields of live SSE messages, plus their stored
id(an integer) andcreated_.at
chunk: 1always starts a new replay. Drop what you hold for those topics, then apply the frames in order. You're up to date whenchunkequalstotal_.chunks - Replays of older matches can lack fields added since. Treat a missing field like
null.
Note
odds and match_ replay every message sent so far, though only the latest one is current. Late in a match, an odds replay can be several megabytes, and a single frame can pass 1 MB.
Duplicates and gaps
seqstarts at 1 and goes up by 1 within each stream (match, topic and language).- The end of a replay can overlap the first live messages. Drop duplicates on
(match_.id, topic, language, seq) - Rarely, a live message has
seq: null, or0on its translations: we couldn't store it, so it won't appear in any replay. Show it without deduplicating it. - A replay can be up to 5 seconds old. So a message published just before you connected can be missing from both the replay and the live stream. If a stream's
seqskips a number, resubscribe or reconnect a few seconds later to fill the gap.
Ordering
- Within one stream, order messages by
seq. seqis counted separately for each stream, so it can't order messages across topics. Across topics, usetimestamp(when the message was published) or the match minute indata.
Times
All times are UTC. Live messages, acks and replay frames have no zone suffix (2026-10-25T20:26:01.112723). Messages inside a replay, and tips' created_, end in Z. Treat both as UTC. The fractional seconds are left out when they're zero.
Message reference
Each section shows the data of one message type.
Note
Store IDs as 64-bit integers. bet_, wager_ (wsid in odds), market_ (mlid) and pressure id already exceed 32 bits. They're all well within the range JavaScript numbers hold exactly.
ai_ commentary
The strategy's commentary, and any bets it places.
{
"id": "8f4cf6e8-5cf4-4c36-88e9-b58c974e9d78",
"minute": 75,
"period_id": 2,
"period_name": "2nd-half",
"commentary": "Barcelona are dominating the possession charts and forcing errors. Let us grab the 1X2 market for a home win at 2.6 while the price is high.",
"action_type": "snipe_live_bet",
"bet_slips": [
{
"bet_id": 1792964349638601,
"market_line_id": 2552318214,
"market_name": "1X2",
"bet_type_id": 3,
"period_id": 1,
"selection_id": 5,
"selection_name": "Home",
"wager_selection_id": 33142892065,
"odds": 2.6,
"handicap": null,
"handicap_is_line": true,
"specifiers": "",
"odds_type": null,
"stake": 25.0,
"bet_placed_home_score": 1,
"bet_placed_away_score": 1,
"bet_placed_home_corners": 4,
"bet_placed_away_corners": 6,
"im_home_team_id": 80987,
"im_away_team_id": 870,
"confidence": 0.45,
"implied_probability": 0.38,
"confidence_source": "model"
}
]
}idstring or null- The item's UUID. It's the same in every language. It can be
nullon old messages. minuteinteger- Match minute when the strategy acted
period_,id period_integer, stringname 0"Not Started",1"1st-,half" 2"2nd-,half" 3"extra-ortime" 5"penalties"commentarystring- The text, in the stream's language
action_stringtype - What the strategy is doing (see Action types)
bet_array of bet slipsslips - The bets placed by this action. Empty when there are none.
Note
AI minutes don't always go up. The minute on ai_ and ai_ holds still through half-time and can step back at full time. Order a strategy's messages by seq.
Action types
Use them to drive your UI, for example icons or colours.
| Group | action_ | The strategy… |
|---|---|---|
| Betting | snipe_ | bets on a value opportunity |
double_ | adds another bet on an outcome it already backs | |
hedge_ | bets against one of its bets to lock in a result | |
cash_ | takes a profit or cuts a loss | |
cash_ | debates whether to cash out | |
tilt_ | bets aggressively after a loss | |
| Advice | highlight_ | points out value without betting |
warn_ | warns against a bet | |
suggest_ | suggests a long shot for fun | |
| Reactions | react_ | celebrates a goal that helps its bets |
react_ | reacts to a goal that hurts its bets | |
react_ | appreciates a goal it has no stake in | |
react_ | waits on a VAR decision | |
react_ | reacts to a shot off the post or a big save | |
analyze_ | comments on the flow of the game | |
critique_ | blames a player | |
| Mood | sweating | feels the tension late in a close bet |
bragging | gloats after a win | |
coping | explains away a loss | |
rally_ | urges a result ("One more corner!") | |
| Audience | ask_ | asks viewers what they think |
shoutout_ | celebrates with viewers who won | |
| Session | welcome | opens the stream, before or at kick-off |
goodbye | signs off after the match |
Bet slips
ai_ and tips reuse the same fields.
bet_integerid - Unique bet ID. It also appears in
ai_and tips.results market_integerline_ id - IM market line ID (
mlidinodds) market_stringname - For example
"Handicap","Over/,Under" "1X2","1H Over/orUnder" "Corner Handicap" bet_integer or nulltype_ id - IM bet type ID (
btidinodds) period_integer or nullid - IM game period:
1full match,2first half,3second half selection_,id selection_integer, stringname - The selection, for example
5"Home"on 1X2, or3"Over" wager_integer or nullselection_ id - IM wager selection ID (
wsidinodds) oddsnumber- Decimal odds when the bet was placed
handicapnumber or null- The line bet on this selection, for example
-0.5for Home −0.5, or the total on over/under markets.nullon markets without one. handicap_booleanis_ line trueon current slips. Older slips don't have it: see the warning below.specifiers,odds_string or null, integer or nulltype - IM details. Usually
""andnull. stakenumber- Stake, in notional units. PnL uses the same units.
bet_,placed_ home_ score bet_integerplaced_ away_ score - Score when the bet was placed
bet_,placed_ home_ corners bet_integer or nullplaced_ away_ corners - Corners when the bet was placed.
nullon old bets. im_,home_ team_ id im_integer or nullaway_ team_ id - IM team IDs
confidencenumber or null- The strategy's estimate of the chance the bet wins, from 0 to 1. Show it as a percentage.
implied_number or nullprobability 1 /when the bet was placed, from 0 to 1odds confidence_string or nullsource "model"whenconfidenceis the strategy's own estimate."market"when it gave none, soconfidenceequalsimplied_.probability
The three confidence fields are rounded to 2 decimal places. They're all null on old bets, and when the odds were 1 or lower.
Warning
Older bets have the opposite handicap sign. Current bet slips and tips have handicap_. Older ones don't have it, or have false, and on handicap markets (where market_ or market_ contains "Handicap") their handicap is the negative of the line bet. For example, "selection_ without the marker was a bet on Away +0.25, so flip the sign when you display it. Over/under lines and the odds topic were always correct.
ai_ results
The strategy's results for the match, about once a minute. Each message gives the full picture so far, not a change.
{
"settled_pnl": 15.25,
"unsettled_pnl": 0.0,
"minute": 76,
"bets": [
{
"bet_slip": { "bet_id": 1792959428604594, "market_name": "1H Over/Under", "selection_name": "Over", "odds": 1.84, "handicap": 1.25, "stake": 25.0 },
"state": "half_lost",
"live_state": "half_lost",
"settled": true,
"pnl": -12.5
},
{
"bet_slip": { "bet_id": 1792964349638601, "market_name": "1X2", "selection_name": "Home", "odds": 2.6, "handicap": null, "stake": 25.0 },
"state": "pending",
"live_state": "lost",
"settled": false,
"pnl": 0.0
}
]
}The bet_ objects are shortened here. Real ones have every bet slip field.
settled_numberpnl - Profit or loss from settled bets. This is the strategy's PnL.
unsettled_numberpnl - Always
0: a bet adds to PnL only once it settles minuteinteger- Match minute
betsarray of object- Every bet the strategy has placed in this match
Each entry in bets:
bet_objectslip - The bet, as in
ai_commentary statestringpending,won,lost,half_,won half_orlost pushlive_stringstate - What the bet would settle as if the match ended now (same values). It equals
stateonce the bet settles. Some old messages don't have it. settledbooleantrueonce the result is finalpnlnumber- Profit or loss on this bet.
0until it settles.
match_ commentary
Text commentary from our data provider. It's translated into each language.
{
"id": 11580888,
"minute": 41,
"extra_minute": null,
"comment": "Goal! Real Madrid lead 1-0 against Barcelona as Kylian Mbappé scores with a right-footed shot from the center of the box into the bottom left corner.",
"is_goal": true,
"is_important": true
}idinteger- Line ID. It's the same in every language.
minute,extra_integer, integer or nullminute - Match minute, and minutes into stoppage time:
90and8mean 90+8'.extra_isminute nulloutside stoppage time. commentstring- The text, in the stream's language
is_booleangoal trueon goal linesis_booleanimportant trueon key moments
minute is always set. A line without its own minute gets the minute of the line before it, or 0 if there's none.
Note
Messages are never withdrawn. If our data provider rewords a commentary line, you get both versions.
event
Structured match events.
{
"id": 158411184,
"type_id": 14,
"type_name": "Goal",
"minute": 61,
"extra_minute": null,
"period_id": 7194994,
"side": "home",
"participant_id": 83,
"player_id": 160258,
"player_name": "Raphinha",
"related_player_id": 37288001,
"related_player_name": "Pedri",
"result": "1-1",
"info": "Right foot shot",
"addition": "2nd Goal",
"sort_order": 2,
"rescinded": null,
"coach_id": null,
"on_bench": false,
"injured": null
}idinteger- Event ID
type_,id type_integer, stringname - Event type (see Event types)
minute,extra_integer, integer or nullminute - Match minute and minutes into stoppage time. For penalty shootout kicks,
minuteis the kick number. period_integer or nullid - ID of the period it happened in. It matches
periods[].inid match_.status sidestring"home"or"away". Events without a team are reported as"home".participant_integer or nullid - Team ID
player_,id player_integer or null, string or nullname - The main player: the scorer, the booked player or the player coming on
related_,player_ id related_integer or null, string or nullplayer_ name - The other player: the assist, or the player going off
resultstring or null- Score after a goal, for example
"1-1" infostring or null- Detail, for example
"Right foot shot"or"Unsportsmanlike conduct" additionstring or null- Label, for example
"2nd Goal","6th Yellowcard"or"Goal disallowed" sort_integer or nullorder - How many events of this type there have been so far (the 2 in "2nd Goal"). It doesn't order events within a minute.
rescinded,on_boolean or nullbench - Other details, often
null coach_integer or nullid - Other details, often
null injuredboolean, string or null- Other details, often
null
Only id, type_, type_, minute and side are always set.
Note
Events are sent once and never updated. A goal later disallowed stays in the feed, followed by a VAR event with addition: "Goal disallowed".
Event types
type_ | type_ |
|---|---|
14 | Goal |
15 | Own Goal |
16 | Penalty (scored) |
17 | Missed Penalty |
18 | Substitution |
19 | Yellowcard |
20 | Redcard |
21 | Yellow/Red card |
10 | VAR |
1697 | VAR_CARD |
22 | Penalty Shootout Miss |
23 | Penalty Shootout Goal |
Other Sportmonks event types may appear. Corners aren't sent as events. VAR events say what happened in addition, for example "Pending VAR", "Goal disallowed" or "Penalty awarded".
pressure
How much pressure each team is putting on, minute by minute. Each minute has two messages, one per team.
{ "id": 7308289375, "minute": 23, "pressure": 45.3, "participant_id": 83, "side": "home" }idinteger- Reading ID
minuteinteger- Match minute
pressurenumber- That team's pressure in that minute, from 0 to 100
sidestring or null"home"or"away". It can benullif the team isn't recognised.participant_integer or nullid - Team ID
To show momentum, compare the two teams' values for each minute.
Note
Not every competition has pressure. Some, currently including the UEFA Champions League, send no pressure data, so their matches have no pressure messages.
match_ status
The full current state of the match. It's sent about once a minute, and only once during half-time.
{
"id": 19732648,
"name": "FC Barcelona vs Real Madrid",
"state": { "name": "2nd Half", "short_name": "2nd" },
"result_info": null,
"starting_at": "2026-10-25 20:00:00",
"scores": [
{ "score": { "goals": 0, "participant": "home" }, "description": "CURRENT", "participant_id": 83 },
{ "score": { "goals": 1, "participant": "away" }, "description": "CURRENT", "participant_id": 3468 },
{ "score": { "goals": 0, "participant": "home" }, "description": "1ST_HALF", "participant_id": 83 },
{ "score": { "goals": 1, "participant": "away" }, "description": "1ST_HALF", "participant_id": 3468 }
],
"periods": [
{ "id": 7194899, "fixture_id": 19732648, "type_id": 1, "description": "1st-half", "sort_order": 1, "started": 1792958554, "ended": 1792961389, "ticking": false, "minutes": 47, "seconds": 15, "time_added": 2, "has_timer": false },
{ "id": 7194994, "fixture_id": 19732648, "type_id": 2, "description": "2nd-half", "sort_order": 2, "started": 1792962497, "ended": null, "ticking": true, "minutes": 53, "seconds": 43, "time_added": null, "has_timer": true }
]
}id,nameinteger, string- Fixture ID and name
stateobject or null- Match state:
nameandshort_, both strings (see Match states)name result_string or nullinfo - Result text after the match, for example
"Real Madrid won after full-.time." nullbefore. starting_stringat - Kick-off in UTC, written
"2026-10-25 20:00:00"(with a space, notT) scoresarray of object or null- Scores, one entry per team for each
description(see Scores) periodsarray of object or null- The periods played so far (see Periods)
Scores
score.integergoals - Goals
score.stringparticipant "home"or"away"descriptionstring- Which score this is (see below)
participant_integerid - Team ID
CURRENT is the live score. 1ST_ is the half-time score, 2ND_ the score after the second half (so far), and 2ND_ the goals scored in the second half alone. ET, ET_, ET_ and PENALTY_ appear when extra time or a shootout is played.
Periods
idinteger- Period ID. Events'
period_points here.id type_,id descriptioninteger, string1"1st-,half" 2"2nd-,half" 3"extra-ortime" 5"penalties"sort_integerorder - Order of the period
started,endedinteger or null- Unix time in seconds.
endedisnullwhile the period runs. tickingbooleantruewhile the clock runsminutes,secondsinteger or null- The match clock, for example 53:43. The second half carries on from 45.
minutesisnullif the provider sends an implausible value. time_integer or nulladded - Stoppage time announced, in minutes
has_booleantimer truewhile the provider times the period. It'sfalseonce the period ends, and for penalties.fixture_integerid - Fixture ID
Note
Period clocks can jump. They come from our data provider, and now and then they jump ahead or back, for example at second-half kick-off. Don't assume they only increase.
Match states
state. / state.: Not Started / NS, 1st Half / 1st, Half Time / HT, 2nd Half / 2nd, Extra Time / et, Extra Time - Break / ETB, Penalties / PEN, Break / BRK, Full Time / FT, After Extra Time / AET, After Penalties / FTP, Postponed / POST, Delayed / DELA, Suspended / SUSP, Interrupted / INT, Abandoned / ABAN, Awaiting Updates / AU.
State codes
state_ and state_ in fixtures, and match_ in tips, use these codes:
- Not started:
1NS - In play:
2INPLAY_1ST_HALF,3HT,4BREAK,22INPLAY_2ND_HALF,6INPLAY_ET,21EXTRA_TIME_BREAK,23INPLAY_ET_2ND_HALF,25PEN_BREAK,9INPLAY_PENALTIES - Finished:
5FT,7AET,8FT_PEN - Other:
10POSTPONED,11SUSPENDED,12CANCELLED,13TBA,14WO,15ABANDONED,16DELAYED,17AWARDED,18INTERRUPTED,19AWAITING_UPDATES,20DELETED,26PENDING
odds
Every live market for the match, in IM's compact format. Each message holds the full list, so replace what you have.
{
"ht": "Barcelona",
"at": "Real Madrid",
"htid": 80987,
"atid": 870,
"hs": 0,
"as": 1,
"rbt": "2H 53:53",
"mls": [
{
"btn": "Handicap",
"btid": 1,
"mlid": 2552318204,
"gp": 1,
"mll": 1,
"isl": false,
"pen": null,
"peid": null,
"wss": [
{ "sen": "Home", "seid": 1, "wsid": 33142524486, "h": 0.5, "dih": "-0.5", "o": 0.86, "ol": [{ "ot": 3, "ov": { "A": "1.86" } }], "sp": "" },
{ "sen": "Away", "seid": 2, "wsid": 33142524487, "h": 0.5, "dih": "+0.5", "o": -0.94, "ol": [{ "ot": 3, "ov": { "A": "2.06" } }], "sp": "" }
]
}
]
}Top level
ht,atstring- Home and away team names, as IM names them
htid,atidinteger or null- IM team IDs
hs,asinteger or null- Current score, according to IM
rbtstring or null- IM's match clock, for example
"2H 53:53" mlsarray of object- Market lines
Market lines (mls)
btnstring- Market name, for example
"Handicap","1H Over/orUnder" "Corner Handicap" btidinteger- IM bet type ID (
bet_on bet slips)type_ id mlidinteger- Market line ID (
market_on bet slips)line_ id gpinteger or null- Game period:
1full match,2first half,3second half mllinteger- Line level:
1is the main line, and2and above are alternative lines islbooleantruewhen the market is locked and can't be bet onwssarray of object- Selections
pen,peidstring or null, integer or null- Old period fields, usually
null
Selections (wss)
senstring or null- Selection name, for example
"Home","Over","Draw"or"1-2" seidinteger or null- Selection ID (
selection_on bet slips)id wsidinteger or null- Wager selection ID (
wager_on bet slips)selection_ id olarray of object- The decimal price, as a string:
[{"ot": 3, "ov": {"A": "1.86"}}]. Use this for prices. It can be empty. onumber or null- IM's raw price. Its format depends on the market, so use
olinstead. hnumber or null- The line. On handicap markets, both selections carry the same number: the handicap Home gives.
h: 0.5means Home −0.5 and Away +0.5. On over/under markets, it's the total. dihstring or null- The line as IM displays it for this selection, for example
"-0.5"or"+0.5/(a quarter line, split across two lines)1" spstring or null- Specifiers, usually
""
Warning
Read prices from ol, not o. IM's raw price in o is in Malay format on handicap and over/under markets and decimal on the others, so the same number means different odds.
Tips
GET / returns the strategies' bets as tips: the bet, a short written reason, and whether you can still follow it.
languagestringen(default),zh,viorth.allreturns400.strategy_stringid - Only tips from this strategy
match_integerid - Only tips for this match
live_booleanonly true(default): only tips you can still follow now.false: the newest tips whatever their status, each with its current status.
You get up to 200 tips, newest first. Each bet becomes one tip per language.
A tip is live (is_) when all of these are true:
- the match is in play
- the tip is less than 30 minutes old
- the bet hasn't settled, and the strategy hasn't cashed it out or hedged it
- the score hasn't changed since the bet was placed
- the same selection and line are still on offer, unlocked, at odds of at least
minimum_odds
{
"bet_id": 1792964349638601,
"match_id": 19732648,
"strategy_id": "sister-song-v1",
"language": "en",
"market_type": "1X2",
"selection": "Home",
"handicap": null,
"handicap_is_line": true,
"odds": 2.6,
"odds_type": "decimal",
"minimum_odds": 2.6,
"current_odds": 2.62,
"probability": 0.45,
"implied_probability": 0.38,
"estimated_odds": 2.2222,
"expected_value": 0.17,
"bet_type_id": 3,
"selection_id": 5,
"period_id": 1,
"market_line_id": 2552318214,
"im_competition_id": 130,
"home_team_id": 83,
"away_team_id": 3468,
"home_team_name": "FC Barcelona",
"away_team_name": "Real Madrid",
"placed_minute": 75,
"placed_home_score": 1,
"placed_away_score": 1,
"tips_summary": "FC Barcelona are dominating possession and applying sustained attacking pressure as the match enters the final stages.",
"tips_reasoning": "- FC Barcelona hold 60 percent of the ball possession and lead the total shots count 14 to 8.\n- The hosts have generated 44 dangerous attacks compared to Real Madrid's 23.\n- Barcelona lead the shots inside the box with 9 attempts against Real Madrid's 4.",
"created_at": "2026-10-25T21:39:10.767092Z",
"is_live": true,
"bet_state": "pending",
"settled": false,
"current_home_score": 1,
"current_away_score": 1,
"current_minute": 76,
"match_state": "INPLAY_2ND_HALF"
}bet_,id match_integerid - Which bet and match
strategy_,id languagestring- Which strategy, and the tip's language
market_,type selectionstring- Market and selection, as on the bet slip
handicapnumber or null- The line, as on the bet slip
handicap_booleanis_ line trueon current tips. On older ones, flip the sign: see Bet slips.oddsnumber- Odds when the bet was placed
odds_stringtype - Always
"decimal" minimum_numberodds - The lowest odds at which the tip is still worth taking. Currently the same as
odds. current_number or nullodds - Latest decimal odds for the same selection and line.
nullif it's no longer on offer. probabilitynumber or null- The strategy's estimate of the chance the bet wins, from 0 to 1.
nullif it gave none. implied_number or nullprobability 1 /when the bet was placedodds estimated_number or nullodds 1 /probability expected_number or nullvalue probability × odds − 1:0.17means +17%bet_,type_ id period_integer or nullid - IM IDs, as on the bet slip
selection_,id market_integerline_ id - IM IDs, as on the bet slip
im_integer or nullcompetition_ id - IM competition ID
home_,team_ id away_integerteam_ id - Team IDs
home_,team_ name away_stringteam_ name - Team names, in the tip's language
placed_,minute placed_,home_ score placed_integeraway_ score - Minute and score when the bet was placed
tips_stringsummary - One line on why
tips_stringreasoning - Up to 3 bullet points, as markdown lines starting with
- created_stringat - When the tip was made, in UTC
is_booleanlive - Whether you can still follow the tip (see above)
bet_string or nullstate - The bet's state (
pending,won, …).nullwhen unknown. settledboolean- Whether the result is final.
falsewhen unknown. current_,home_ score current_,away_ score current_integer or nullminute - The match now.
nullwhen unknown. match_string or nullstate - A state code name, or
"unknown".nullwhen unknown.
Staying up to date
This guide always describes the current production API, at song.brainanalytics.co/docs.
- Changelog. Every change is listed, newest first, at song.brainanalytics.co/docs/changelog. To hear about changes as they happen, subscribe to its feed,
https://, in a feed reader or in Slack withsong. brainanalytics. co/ docs/ changelog. xml /.feed subscribe https:// song. brainanalytics. co/ docs/ changelog. xml - Additions come without notice. We add fields, message types, topics and values (such as new
action_values) as we go. Ignore anything you don't recognise.type - Breaking changes come with notice. Before we remove or rename anything, or change what a value means, we tell you in advance and release it to staging first.
Glossary
- Strategy: an AI persona that watches a match, comments on it and places bets. Each has a text ID, such as
sister-, and its own two topics.song- v1 - Topic: one kind of message for a match, such as
match_orstatus ai-. See Topics and languages.commentary- sister- song- v1 - Language:
en,zh,viorth. Per-language topics are published once in each language, and the others once, withlanguage: "all". - Stream: one topic of one match in one language.
seqcounts the messages in a stream. - Replay: the
snapshotframes that start every connection and subscription, holding everything already published. See Replay frames. seq: a message's position in its stream, from 1. Use it to drop duplicates and to order the stream.- Match ID: our data provider's fixture ID:
idin the fixture lists,match_everywhere else.id - Handicap line: the handicap on the selection bet on, for example
-0.5for Home −0.5. See Bet slips. - Tip: a strategy's bet, written up with its reason, that you can follow while it's live. See Tips.
- IM: the sportsbook whose markets and odds the strategies bet on. Its IDs appear in
odds, bet slips and tips. - Sportmonks: our data provider for fixtures, match events, commentary, pressure and match status. Fixture, team and event type IDs are theirs.