Chat Assistant API — v1

Developer Reference

A server-to-server intelligence platform for white-label sportsbook operators and sports media partners. Conversational football Q&A, behavioural signal ingestion, and betting insights — all under a single authenticated API key.

What the API provides

• Chat Stream— multi-turn conversational football Q&A streamed as newline-delimited JSON events, ready to relay to the end-user's UI.
• Intelligence Signals — fire-and-forget ingestion of behavioural events (page views, market clicks, bet placements) that feed the personalisation engine.
• Betting Insights — per-match AI-generated betting intelligence cards (Phase 2).

High-level request flow

Integration model

The Chat Assistant API is a server-to-server API. Your operator backend authenticates with a Bearer key and relays events between your end-users and the API. No browser or mobile client should ever call this API directly.

Why server-to-server?

• Your operator key stays private — no risk of client-side leakage.
• You control user identity mapping — the API works with your opaque operatorUserId; no PII reaches Sensible Stats.
• You can apply your own content filtering, rate limiting, or caching before relaying events.
• Signals and personalisation data are scoped per-operator — strict data isolation between partners.

Authentication

Every request must include a valid API key as a Bearer token in the Authorization header. Keys are issued per operator.

Authorization: Bearer <YOUR_OPERATOR_API_KEY>
Content-Type: application/json

Contact partners@sensiblestats.com to obtain an API key.

Rate limits

Rate limits are enforced per operator API key. Your specific limits are defined in your partnership agreement. The values below are indicative.

On limit exceeded the API returns 429 with error code OperatorRateLimitExceeded and a Retry-After header.

Chat stream

Request body

Send a JSON object. Maximum payload size is 8 KB.

{
  "message": "How many Premier League goals did Haaland score in 2023/24?",
  "conversationId": "conv_9a1b2c3d",
  "turnIdempotencyKey": "turn_idem_00123",
  "userContext": {
    "operatorUserId": "usr_abc123",
    "defaultLanguage": "en"
  },
  "debug": false
}

NDJSON event contract

Every line in the response body is a JSON object followed by \n. Consume the stream line-by-line. Each object shares this envelope:

{
  "type": "<event_type>",
  "requestId": "req_8f3a92b1",
  "data": { ... }
}

Typical event sequence

{"type":"progress","requestId":"req_abc","data":{"phase":"resolving","message":"Resolving entities..."}}
{"type":"progress","requestId":"req_abc","data":{"phase":"querying","message":"Running stats query..."}}
{"type":"text","requestId":"req_abc","data":{"text":"## Erling Haaland — Premier League 2023/24\n\n..."}}
{"type":"intent_chip","requestId":"req_abc","data":{"intent":{"label":"Top scorers 2023/24","query":"Who were the top 5 scorers?"}}}
{"type":"turn_complete","requestId":"req_abc","data":{"conversationId":"conv_9a1b2c3d","assistantText":"...","totalLatencyMs":3104}}

Event types

Event data schemas

progress

{
  "type": "progress",
  "requestId": "req_abc",
  "data": {
    "phase": "resolving",
    "message": "Resolving entities..."
  }
}

text

{
  "type": "text",
  "requestId": "req_abc",
  "data": {
    "text": "## Erling Haaland — Premier League 2023/24\n\nErling Haaland scored **27 goals** in 31 appearances..."
  }
}

intent_chip

{
  "type": "intent_chip",
  "requestId": "req_abc",
  "data": {
    "intent": {
      "label": "Top scorers in 2023/24",
      "query": "Who were the top 5 scorers in the Premier League 2023/24?"
    }
  }
}

error (mid-stream terminal)

{
  "type": "error",
  "requestId": "req_abc",
  "data": {
    "code": "InternalError",
    "message": "An unexpected error occurred. Please try again.",
    "terminal": true
  }
}

Turn complete event

The turn_complete event is always the last event in a successful stream. It carries the full assembled answer, the conversation ID for the next turn, and diagnostic metadata.

{
  "type": "turn_complete",
  "requestId": "req_abc",
  "data": {
    "conversationId": "conv_9a1b2c3d",
    "assistantText": "## Erling Haaland...",
    "routeDecision": "stats_agent",
    "isAgentRouted": true,
    "totalLatencyMs": 3104,
    "actions": [],
    "cards": [],
    "slip": null,
    "onboarding": null,
    "toolCallLog": []
  }
}

Intelligence signals

The Intelligence Signal endpoint is a fire-and-forget behavioural data pipeline. Send signals whenever your users interact with sports content — match pages, player profiles, markets. Sensible Stats processes them asynchronously to build a per-user entity interest profile that is injected into the chat assistant's context on future turns.

The result is an assistant that opens conversations with personalised greetings, surfaces stats about entities the user cares about, and orders suggested follow-ups around observed interests — without you building or maintaining a recommendation system yourself.

Signal endpoint

Request body

{
  "signalType": 2,
  "entityType": 3,
  "entityId": "player_123456",
  "operatorUserId": "usr_abc123"
}

Response — 202 Accepted

{
  "requestId": "req_8f3a92b1",
  "acceptedAtUtc": "2025-06-21T14:30:00.000Z"
}

Signal types

Pass the integer value in the signalType field.

Entity types

Pass the integer value in the entityType field.

Betting insights

Returns AI-generated pre-match betting intelligence cards for a given football match. Cards surface key stats, recent form, head-to-head records, and model-derived confidence signals to help operators enrich their match pages.

GET /api/betting-insights?matchId=match_88abc123&language=en
Authorization: Bearer <YOUR_OPERATOR_API_KEY>

Health endpoints

Probe endpoints for container orchestration liveness and readiness checks. No authentication required.

Error format

All HTTP-level errors (4xx/5xx) use RFC 7807 ProblemDetails with two additional fields: requestId and errorCode. Mid-stream errors use the error NDJSON event type instead.

{
  "type": "https://api.sensiblestats.com/errors/validation",
  "title": "Validation error",
  "status": 422,
  "detail": "The 'message' field is required and must not be empty.",
  "requestId": "req_8f3a92b1",
  "errorCode": "ValidationError"
}

Error codes

Integration workflow

A typical integration involves three steps: provision credentials, relay the chat stream, and optionally enrich with signals.

Personalisation via signals

Personalisation is additive — it improves the chat experience without requiring any changes to your chat relay. Send signals whenever possible, but the chat endpoint works without them.

How it works

1. 1. Signal ingestion. Your backend sends POST /api/intelligence/signal with an operatorUserId and the entity they interacted with.
2. 2. Profile building. Sensible Stats processes signals asynchronously to build an entity interest graph per user: which teams, players, and competitions they follow.
3. 3. Context injection. When the same operatorUserId appears in a chat turn's userContext, the assistant automatically receives their interest profile as context.
4. 4. Personalised responses. The assistant opens with greetings referencing the user's favourite clubs, prioritises stats for their preferred entities, and orders suggested follow-ups around observed interests.

Best practices

Code examples

Node.js — backend relay (TypeScript)

A minimal Express endpoint that relays the NDJSON stream from the Chat Assistant API to the browser via Server-Sent Events.

import express from "express";

const CHAT_API = "https://api.sensiblestats.com";
const API_KEY = process.env.SENSIBLE_STATS_API_KEY!;

const app = express();
app.use(express.json());

app.post("/chat", async (req, res) => {
  const { message, conversationId, userId } = req.body;

  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");

  const upstream = await fetch(`${CHAT_API}/api/chat-stream`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message,
      conversationId,
      userContext: { operatorUserId: userId, defaultLanguage: "en" },
    }),
  });

  if (!upstream.ok || !upstream.body) {
    res.status(502).json({ error: "upstream_error" });
    return;
  }

  const reader = upstream.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const chunk = decoder.decode(value, { stream: true });
    // Forward each NDJSON line as an SSE event
    for (const line of chunk.split("\n")) {
      if (line.trim()) res.write(`data: ${line}\n\n`);
    }
  }

  res.end();
});

Node.js — fire-and-forget signal

async function sendSignal(
  operatorUserId: string,
  signalType: number,
  entityType: number,
  entityId: string,
): Promise<void> {
  // Don't await — fire and forget
  fetch("https://api.sensiblestats.com/api/intelligence/signal", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SENSIBLE_STATS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ signalType, entityType, entityId, operatorUserId }),
  }).catch((err) => console.error("[signal] delivery failed", err));
}

// On match page view:
sendSignal("usr_abc123", 1 /* MatchPageView */, 1 /* Match */, "match_88abc123");

React — rendering the stream

import { useState } from "react";
import ReactMarkdown from "react-markdown";

export function ChatWidget() {
  const [answer, setAnswer] = useState("");
  const [chips, setChips] = useState<string[]>([]);
  const [convId, setConvId] = useState<string | undefined>();

  async function send(message: string) {
    setAnswer("");
    setChips([]);

    const res = await fetch("/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ message, conversationId: convId }),
    });

    const reader = res.body!.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      const text = decoder.decode(value, { stream: true });
      for (const line of text.split("\n")) {
        const clean = line.startsWith("data: ") ? line.slice(6) : line;
        if (!clean.trim()) continue;
        const event = JSON.parse(clean);

        if (event.type === "text") setAnswer(event.data.text);
        if (event.type === "intent_chip") {
          setChips((c) => [...c, event.data.intent.label]);
        }
        if (event.type === "turn_complete") setConvId(event.data.conversationId);
      }
    }
  }

  return (
    <div>
      <ReactMarkdown>{answer}</ReactMarkdown>
      <div className="flex gap-2">
        {chips.map((c) => (
          <button key={c} onClick={() => send(c)} className="rounded-full border px-3 py-1 text-sm">
            {c}
          </button>
        ))}
      </div>
    </div>
  );
}

Python — backend relay

import httpx
import json
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse

app = FastAPI()
CHAT_API = "https://api.sensiblestats.com"
API_KEY = os.environ["SENSIBLE_STATS_API_KEY"]

@app.post("/chat")
async def relay_chat(request: Request):
    body = await request.json()

    async def event_stream():
        async with httpx.AsyncClient(timeout=30) as client:
            async with client.stream(
                "POST",
                f"{CHAT_API}/api/chat-stream",
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json",
                },
                json={
                    "message": body["message"],
                    "conversationId": body.get("conversationId"),
                    "userContext": {
                        "operatorUserId": body.get("userId"),
                        "defaultLanguage": "en",
                    },
                },
            ) as r:
                async for line in r.aiter_lines():
                    if line:
                        yield f"data: {line}\n\n"

    return StreamingResponse(event_stream(), media_type="text/event-stream")

cURL — quick test

# Chat stream (prints raw NDJSON lines)
curl -s -N \
  -H "Authorization: Bearer <YOUR_OPERATOR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"message":"How many goals did Salah score in 2023/24?"}' \
  https://api.sensiblestats.com/api/chat-stream

# Intelligence signal
curl -s -X POST \
  -H "Authorization: Bearer <YOUR_OPERATOR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"signalType":1,"entityType":1,"entityId":"match_88abc123","operatorUserId":"usr_abc123"}' \
  https://api.sensiblestats.com/api/intelligence/signal

Changelog