API & WebhooksAPI & Webhooks

OverviewÜberblick

The Director API gives you programmatic access to the same live signals the AI acts on — so you can build the engagement layer into your own dashboards, overlays and automations.Die Director-API gibt dir programmatischen Zugriff auf dieselben Live-Signale, auf die auch die KI reagiert – damit du die Engagement-Ebene in deine eigenen Dashboards, Overlays und Automationen einbaust.

With the API and webhooks you can:Mit der API und den Webhooks kannst du:

• Read a channel's live energy score in real time.Den Live-Energiewert eines Kanals in Echtzeit auslesen.
• Manage your cue library and fire polls, quizzes or shout-outs on demand.Deine Cue-Bibliothek verwalten und Umfragen, Quizze oder Shout-outs auf Abruf auslösen.
• Pull retention analytics for any past stream session.Verweildauer-Analysen für jede vergangene Stream-Session abrufen.
• Subscribe to webhooks so events like energy dips and fired cues arrive in your backend the moment they happen.Webhooks abonnieren, damit Events wie Energieabfälle und ausgelöste Cues in dem Moment in deinem Backend landen, in dem sie passieren.

The API is a standard REST interface: HTTPS requests, JSON responses, and predictable resource-oriented URLs.Die API ist eine gängige REST-Schnittstelle: HTTPS-Anfragen, JSON-Antworten und vorhersehbare, ressourcenorientierte URLs.

QuickstartSchnellstart

Four steps take you from zero to your first live reading:Vier Schritte bringen dich von null zu deiner ersten Live-Messung:

1. Get your API key. In the dashboard, open Settings → Developers and create a key. Studio plan only.Hol dir deinen API-Schlüssel. Öffne im Dashboard Einstellungen → Entwickler und erstelle einen Schlüssel. Nur im Studio-Plan.
2. Connect a channel (Twitch, YouTube, Kick or OBS) if you haven't already — the API reads channels you've linked.Verbinde einen Kanal (Twitch, YouTube, Kick oder OBS), falls noch nicht geschehen – die API liest verknüpfte Kanäle.
3. Make your first call to read that channel's live energy.Mach deinen ersten Aufruf, um die Live-Energie des Kanals auszulesen.
4. Subscribe to a webhook to stop polling and get events pushed to you instead.Abonniere einen Webhook, um nicht mehr zu pollen und Events stattdessen zugestellt zu bekommen.

curl https://api.castfinity.ai/v1/channels/chn_8f2a4d/energy \
  -H "Authorization: Bearer cf_live_9d1c7b2a4e8f0c4e2"

AuthenticationAuthentifizierung

Every request must be authenticated with an API key, sent as a Bearer token in the Authorization header. Requests without a valid key return 401 Unauthorized.Jede Anfrage muss mit einem API-Schlüssel authentifiziert werden, gesendet als Bearer-Token im Authorization-Header. Anfragen ohne gültigen Schlüssel liefern 401 Unauthorized.

Authorization: Bearer cf_live_9d1c7b2a4e8f0c4e2

Keys come in two flavours: cf_test_… for sandbox data and cf_live_… for production. You can create and revoke keys any time under Settings → Developers.Schlüssel gibt es in zwei Varianten: cf_test_… für Sandbox-Daten und cf_live_… für die Produktion. Du kannst Schlüssel jederzeit unter Einstellungen → Entwickler erstellen und widerrufen.

Base URL & rate limitsBasis-URL & Rate-Limits

All endpoints are relative to a single versioned base URL:Alle Endpunkte sind relativ zu einer einzigen versionierten Basis-URL:

https://api.castfinity.ai/v1

Requests are limited to 600 requests per minute per API key. Every response includes the current budget in its headers; when you exceed it you receive 429 Too Many Requests and should retry after the window resets.Anfragen sind auf 600 Anfragen pro Minute pro API-Schlüssel begrenzt. Jede Antwort enthält das aktuelle Budget in ihren Headern; bei Überschreitung erhältst du 429 Too Many Requests und solltest nach dem Zurücksetzen des Fensters erneut senden.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1784560000

ChannelsKanäle

A channel represents one connected streaming destination. List your channels or retrieve a single one by ID.Ein Kanal steht für ein verbundenes Streaming-Ziel. Liste deine Kanäle auf oder rufe einen einzelnen per ID ab.

The channel objectDas Kanal-Objekt

{
  "id": "chn_8f2a4d",
  "platform": "twitch",
  "display_name": "nightowl_live",
  "status": "live",
  "connected_at": "2026-05-02T18:11:44Z"
}

EnergyEnergie

The energy reading is the heart of the Director — a per-second score from 0–100 of how alive the room feels, plus the direction it's trending.Die Energiemessung ist das Herz des Directors – ein Wert pro Sekunde von 0–100, wie lebendig der Raum wirkt, plus die Richtung des Trends.

{
  "channel_id": "chn_8f2a4d",
  "score": 41,
  "trend": "falling",
  "viewers": 2140,
  "measured_at": "2026-07-20T14:32:07Z"
}

CuesCues

Cues are the interactions the Director can fire: polls, quizzes, reaction bursts and shout-outs. List your library, create new cues, or fire one manually.Cues sind die Interaktionen, die der Director auslösen kann: Umfragen, Quizze, Reaktions-Bursts und Shout-outs. Liste deine Bibliothek auf, erstelle neue Cues oder löse einen manuell aus.

Create a cue — body parametersCue erstellen — Body-Parameter

curl -X POST \
  https://api.castfinity.ai/v1/channels/chn_8f2a4d/cues/cue_poll_01/fire \
  -H "Authorization: Bearer cf_live_9d1c7b2a4e8f0c4e2"

{
  "cue_id": "cue_poll_01",
  "channel_id": "chn_8f2a4d",
  "status": "firing",
  "fired_at": "2026-07-20T14:32:08Z"
}

Sessions & analyticsSessions & Analysen

Each stream is recorded as a session. Retrieve retention analytics to see how the energy curve behaved and which cues saved which moments.Jeder Stream wird als Session erfasst. Rufe Verweildauer-Analysen ab, um zu sehen, wie sich die Energiekurve verhalten hat und welche Cues welche Momente gerettet haben.

{
  "session_id": "ses_20a7",
  "duration_minutes": 118,
  "avg_energy": 63,
  "peak_viewers": 3480,
  "retention_lift": 0.37,
  "cues_fired": 14,
  "cues_recovered": 11
}

ErrorsFehler

The API uses conventional HTTP status codes. Errors return a JSON body with a machine-readable code and a human-readable message.Die API verwendet gängige HTTP-Statuscodes. Fehler liefern einen JSON-Body mit einem maschinenlesbaren code und einer menschenlesbaren message.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

WebhooksWebhooks

Webhooks push events to your server the instant they happen — no polling required. Register an endpoint, choose the events you care about, and the Director delivers a signed JSON payload every time one fires.Webhooks schieben Events in dem Moment an deinen Server, in dem sie passieren – kein Polling nötig. Registriere einen Endpunkt, wähle die relevanten Events, und der Director stellt bei jedem Auslösen einen signierten JSON-Payload zu.

Subscribe to a webhookWebhook abonnieren

Register an HTTPS endpoint and list the events you want. Manage your subscriptions with the same resource.Registriere einen HTTPS-Endpunkt und liste die gewünschten Events auf. Verwalte deine Abos über dieselbe Ressource.

curl -X POST https://api.castfinity.ai/v1/webhooks \
  -H "Authorization: Bearer cf_live_9d1c7b2a4e8f0c4e2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/castfinity",
    "events": ["energy.dip_detected", "cue.fired"]
  }'

{
  "id": "whk_5b91c2",
  "url": "https://your-app.com/hooks/castfinity",
  "events": ["energy.dip_detected", "cue.fired"],
  "signing_secret": "whsec_2f6a...b0d1",
  "status": "active"
}

Event typesEvent-Typen

Payload & verificationPayload & Verifizierung

Every delivery is an HTTP POST to your endpoint with a JSON body wrapped in a common envelope:Jede Zustellung ist ein HTTP-POST an deinen Endpunkt mit einem JSON-Body in einer gemeinsamen Hülle:

{
  "id": "evt_7c3e9a",
  "type": "energy.dip_detected",
  "created_at": "2026-07-20T14:32:07Z",
  "data": {
    "channel_id": "chn_8f2a4d",
    "score": 41,
    "trend": "falling",
    "viewers": 2140
  }
}

Each request carries a CastFinity-Signature header containing a timestamp and an HMAC-SHA256 signature of timestamp + "." + rawBody, computed with your webhook's signing secret. Verify it before trusting the payload.Jede Anfrage trägt einen CastFinity-Signature-Header mit einem Zeitstempel und einer HMAC-SHA256-Signatur von timestamp + "." + rawBody, berechnet mit dem Signing-Secret deines Webhooks. Verifiziere ihn, bevor du dem Payload vertraust.

CastFinity-Signature: t=1784560327,v1=3a7bf0c9e1d2...8f

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map(p => p.split("="))
  );
  const signed = parts.t + "." + rawBody;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

Retries & deliveryWiederholungen & Zustellung

Respond with any 2xx status within 5 seconds to acknowledge a delivery. If your endpoint returns an error, times out, or is unreachable, the Director retries with exponential backoff:Antworte mit einem beliebigen 2xx-Status innerhalb von 5 Sekunden, um eine Zustellung zu bestätigen. Gibt dein Endpunkt einen Fehler zurück, läuft in ein Timeout oder ist nicht erreichbar, wiederholt der Director mit exponentiellem Backoff:

• Retries over roughly 24 hours (at 1 min, 5 min, 30 min, 2 h, then hourly).Wiederholungen über rund 24 Stunden (nach 1 Min, 5 Min, 30 Min, 2 Std, danach stündlich).
• The id field is stable across retries — use it to make your handler idempotent and avoid processing the same event twice.Das id-Feld bleibt über Wiederholungen stabil – nutze es, um deinen Handler idempotent zu machen und dasselbe Event nicht doppelt zu verarbeiten.
• After 24 hours of failures the subscription is paused and you're notified by email.Nach 24 Stunden Fehlern wird das Abo pausiert und du wirst per E-Mail benachrichtigt.