HTTP API¶

In browser mode, CroStream's whole UI runs on a small JSON API: every button you click in the browser is a POST to /api/<Method>, and everything that updates live arrives over one event stream. Your own tools can use the same API: run a macro from a Stream Deck, show the activity log on another screen, bump a counter from a script, or watch chat from a bot. This page explains the rules, documents the methods that are useful for automation, and lists the rest.

Before you start: it has no login¶

The API is unauthenticated. Anyone who can reach the address crostream serve listens on can do anything the UI can: post to chat, ban viewers, run ads, start a raid, switch OBS scenes, change or delete your setup. That's a deliberate choice for a tool that runs on your own machine or home network, and it puts the safety in your hands:

• Keep the default address (127.0.0.1:8080) unless you need other machines to reach it. Then only programs on the same computer can.
• Only listen on a network you trust, such as your home LAN. Never forward the port on your router, and never listen on a public address.
• To reach it from elsewhere, use an SSH tunnel (ssh -L 8080:127.0.0.1:8080 <host>) or a VPN rather than opening it up.
• Firewall the port on machines that move between networks (a laptop on café Wi-Fi).
• Put a login in front with a reverse proxy if you must expose it more widely; see Reverse proxies.

CroStream does protect you from other web pages and from DNS tricks:

Tools like curl, Stream Deck plugins and scripts send no Origin header, so they pass. Browsers always send one, so a web page on another site can't drive CroStream.

Calling a method¶

Every method is a POST to /api/<Method> with Content-Type: application/json and a body that is a JSON array of the method's arguments, in order. A method without arguments takes [].

curl -s -X POST http://127.0.0.1:8080/api/GetStatus \
  -H 'Content-Type: application/json' -d '[]'

A successful call answers 200 with the result under "result" (null for methods that return nothing):

{"result": [{"id": "twitch", "status": {"state": "connected", "accounts": [{"role": "broadcaster", "login": "crothers"}]}}, …]}

A failed call answers with an error status and a message under "error":

Arguments are decoded strictly: objects may not have fields the method doesn't know, and null is only accepted where an argument is a map (meaning "empty").

The event stream¶

GET /api/events is a Server-Sent Events stream of everything that changes. It starts with a status event holding every integration's status, then sends events as they happen, and a : ping comment every 15 seconds to keep the connection open.

curl -sN http://127.0.0.1:8080/api/events

event: status
data: [{"id":"twitch","status":{"state":"connected",…}},{"id":"obs",…}]

event: feed
data: {"seq":412,"time":"2026-10-11T19:02:11Z","kind":"triggered","source":"twitch","rule":"!lurk","user":"PixelPanda",…}

At most 16 streams can be open at once (the UI uses one per browser tab). A client that reads too slowly is dropped and should reconnect; browsers' EventSource and most SSE libraries do that by themselves.

Methods for automation¶

Macros, triggers and queues are identified by IDs such as seq-01m4nr3cqyykwt94nac1zkhpm6 (macros), bind-… (triggers) and queue-…. IDs never change when you rename something, so they're safe to put in a button. Look them up once with the list methods below, or in the settings file.

All examples use http://127.0.0.1:8080; replace it with your address. To keep them short, they assume this helper:

cs() { curl -s -X POST "http://127.0.0.1:8080/api/$1" -H 'Content-Type: application/json' -d "${2:-[]}"; }

GetStatus¶

GetStatus() returns every integration's status, as the status event does. state is connected, connecting, disconnected, awaiting (waiting for you to log in), disabled or error.

cs GetStatus | jq -r '.result[] | "\(.id): \(.status.state)"'

twitch: connected
obs: connected
steam: disabled
…

GetSequences¶

GetSequences() lists your macros: [{id, name, steps, error}], where steps are short summaries and error says why a macro can't run.

cs GetSequences | jq -r '.result[] | "\(.id)  \(.name)"'

seq-01m4nqwwap513e991pfg4hfsdx  clip
seq-01m4nr3cqyykwt94nac1zkhpm6  Airhorn
seq-01m4nr3cqa2tva4n3aypmpxr1r  BRB

GetSequenceDefs() returns the full definitions instead, as stored in the settings file.

RunSequence¶

RunSequence(id) runs a macro now, as if you clicked Run on it. It runs as you (the broadcaster, when Twitch is logged in), with no trigger involved: no roles, cooldowns or redemption to settle. Only {user}, {user_role} and {rule} are set.

cs RunSequence '["seq-01m4nr3cqyykwt94nac1zkhpm6"]'

{"result": null}

The call returns as soon as the run starts; the outcome appears in the activity feed (the feed event, or GetLog with the run's ID). It fails with 422 when the macro doesn't exist or can't run.

GetBindings and TestBinding¶

GetBindings() lists your triggers: [{id, name, source, trigger, sequenceId, sequenceName, disabled, error, warning}], where trigger is a readable description such as Chat command !lurk · everyone · 30s per user.

TestBinding(id) does what Test does on the Triggers page: runs the trigger's macro with a sample event, ignoring roles and cooldowns and never settling a redemption. Like a real run it returns at once.

cs TestBinding '["bind-01m4nr3chxcwr2jb4t4paxrjbc"]'

RunAction and RunActionOn¶

RunAction(action, params) runs one action right away, without a macro, like the Actions page does. RunActionOn(provider, action, params) runs it on one integration only (for actions more than one provides, such as clip on obs or twitch). Unlike RunSequence, these wait for the action to finish and fail with 422 and its message when it fails.

# Switch OBS to the BRB scene
cs RunAction '["scene.set", {"scene": "BRB"}]'

# Say something in chat
cs RunAction '["chat.send", {"message": "Back in 5! Stretch break."}]'

# Add a death
cs RunAction '["tools.counter", {"name": "deaths", "change": "add", "amount": 1}]'

# Start a 5 minute countdown named "break"
cs RunAction '["overlay.timer", {"timer": "break", "do": "start", "amount": "5m"}]'

# Save a replay clip only (not a Twitch clip)
cs RunActionOn '["obs", "clip", {}]'

Parameters are the action's own, with the names the settings file uses. Values are text, numbers or booleans as the action defines them; {variables} in text are left as typed, since there's no event to fill them from. GetCatalog() lists every action with its parameters:

cs GetCatalog | jq -r '.result[] | "\(.action): \([.params[]?.key] | join(", "))"'

chat.send: message
scene.set: scene
tools.counter: name, change, amount
twitch.timeout: user, duration, reason
…

See Actions for what each one does.

GetFeed¶

GetFeed() returns the recent activity feed, oldest first: the lines the Activity page shows live, the same shape as the feed event.

{
  "seq": 2,
  "time": "2026-10-11T15:09:15.066Z",
  "kind": "action_ok",
  "source": "tools",
  "rule": "quick action",
  "sequence": "quick action",
  "step": "action",
  "provider": "tools",
  "action": "tools.counter",
  "detail": "deaths = 1",
  "run": "run-01m4nr5kdtwp72re2xe48ek5b0"
}

kind is triggered, action_ok, action_error, finished, notice, event and a few more; level (info, warn, error) is set on notices; run groups the lines of one run.

GetLog¶

GetLog(query) searches the stored activity log (the History page's log), newest first. Every field of the query is optional:

# The last 5 failures
cs GetLog '[{"levels": ["error"], "limit": 5}]' | jq -r '.result[] | "\(.time) \(.rule): \(.message // .detail)"'

# Everything one run did
cs GetLog '[{"run": "run-01m4nr5kdtwp72re2xe48ek5b0"}]'

To follow the log from a script, remember the highest id you've seen and ask for {"afterId": <id>} every few seconds, or listen to the feed event.

GetChatFeed¶

GetChatFeed() returns the last 200 chat messages, oldest first, in the shape of the chat event. GetChatLog(query) searches stored chat.

OverlayData, OverlayList and OverlayResetLive¶

OverlayData() returns every overlay data key and its value: chat, events, counters, timers, leaderboards and so on.

cs OverlayData | jq '.result["leaders.bits.stream"]'

OverlayList() lists your overlays (id, name, size, …); OverlayLive(id) returns what macros changed on one (shown or hidden elements, replaced texts); OverlayResetLive(id) drops those changes so the design shows again.

GetIntegrationState¶

GetIntegrationState(id) returns an integration's live state, or null. For queue it lists your queues with what's waiting:

cs GetIntegrationState '["queue"]' | jq '.result[] | {name, waiting, paused}'

{"name": "Song requests", "waiting": 3, "paused": false}

obs gives the current scene, the scene list and the streaming and recording state; steam the game you're playing and your library; discord your status.

Invoke¶

Invoke(id, command, args) runs an integration command, the buttons on its page: connect and disconnect for obs; login, logout and cancel_login for twitch. args is an object of strings, usually {}.

cs Invoke '["obs", "connect", {}]'

login doesn't open a browser in browser mode: the status (the status event, or GetStatus) switches to awaiting with the login page in url. See Twitch login from another machine.

ReloadConfig¶

ReloadConfig() re-reads the settings file after you edit it by hand, like Reload on the Triggers and Macros pages.

cs ReloadConfig

Viewers and points¶

GetViewers(query) pages through the viewer database ({"search": "lunar", "limit": 10}; sort, following, subscriber, activeDays and offset also work). Each viewer has an id (their Twitch user ID), login, name, points, watchSeconds, messages, bits and more. AdjustViewerPoints(id, change) changes a balance, as the Viewers page does; mode is add, subtract or set, and a balance never goes below zero:

cs AdjustViewerPoints '["1004", {"mode": "add", "amount": 500, "reason": "Won the stream quiz"}]'

Recipes¶

Bitfocus Companion¶

Companion's Generic: HTTP Requests connection can call the API from any Stream Deck, X-keys or other control surface it supports.

1. Add a Generic: HTTP Requests connection. Set its base URL to your CroStream address, such as http://192.168.1.50:8080.
2. Create a button. Add a POST action with:
   • URL: /api/RunSequence
   • Body: ["seq-01m4nr3cqyykwt94nac1zkhpm6"]
   • Body content type: application/json
3. Press it. The macro runs, and the Activity page shows the run.

Use /api/RunAction with a body such as ["scene.set", {"scene": "BRB"}] for one-off actions. If Companion runs on another computer, CroStream must listen on an address it can reach (see Browser mode).

Elgato Stream Deck¶

Stream Deck's built-in Website action only opens pages (a GET), so it can't call the API. Use a plugin that sends HTTP requests with a body, such as a "web request" or "API" plugin from the Stream Deck store, and give it:

Pinned macros on the Dashboard and the pop-out Controls window are a no-setup alternative on a second screen or tablet.

A script that reacts to chat¶

Any language with an SSE client works. In Python, with only the standard library:

import json
import urllib.request

BASE = "http://127.0.0.1:8080"


def call(method, *args):
    req = urllib.request.Request(
        f"{BASE}/api/{method}",
        data=json.dumps(list(args)).encode(),
        headers={"Content-Type": "application/json"},
    )
    return json.load(urllib.request.urlopen(req))["result"]


event = None
with urllib.request.urlopen(f"{BASE}/api/events") as stream:
    for raw in stream:
        line = raw.decode().rstrip("\n")
        if line.startswith("event: "):
            event = line[7:]
        elif line.startswith("data: ") and event == "chat":
            msg = json.loads(line[6:])
            if msg["text"].strip().lower() == "!death":
                call("RunAction", "tools.counter", {"name": "deaths", "change": "add", "amount": 1})

For most chat commands a trigger is simpler; use the API when your logic lives outside CroStream.

All methods¶

The browser UI uses every method below. Signatures are Method(argument types) → result.

Methods not listed here (file dialogs, the updater, tray and window settings, pop-out windows) belong to the desktop app and aren't available over HTTP.

Related¶

• Browser mode: running crostream serve and its options.
• Headless setup: a streaming PC with no screen, and reverse proxies.
• Overlay data reference: the data OverlayData returns.
• The settings file: the shapes of macros, triggers and queues.