HTTP API

Base URL: http://127.0.0.1:44555 on the MyHUD PC. From another device, use the address shown in the panel and send the token. See Control from another device.

Routes

Method and path	Description
POST /api/actions/<command>	Runs a command.
GET /api/actions	Lists all the commands and their payload.
GET /api/state	HUD panels, windows, current scene, OBS status.
GET /api/match	Current match. Same as the get_match command.
GET /api/veto	Manual veto in progress. Same as the veto_status command.
GET /api/presets	HUD color presets.
GET /health	Tells if the server runs.

Authentication

On the MyHUD PC, no authentication is needed.

From another device, send the token in one of these headers:

Authorization: Bearer <token>
X-MyHUD-Token: <token>

POST /api/actions/<command>

Send the payload of the command as a JSON body, with Content-Type: application/json. For a command without payload, send no body or {}.

curl

curl -X POST http://127.0.0.1:44555/api/actions/set_map_result \
  -H 'Content-Type: application/json' \
  -d '{"map":1,"scoreA":13,"scoreB":9,"finished":true}'

PowerShell

$body = @{ map = 1; scoreA = 13; scoreB = 9; finished = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post http://127.0.0.1:44555/api/actions/set_map_result `
  -ContentType 'application/json' -Body $body

Python

import requests

res = requests.post(
    "http://127.0.0.1:44555/api/actions/set_map_result",
    json={"map": 1, "scoreA": 13, "scoreB": 9, "finished": True},
)
print(res.status_code, res.json())

TypeScript

const res = await fetch('http://127.0.0.1:44555/api/actions/set_map_result', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ map: 1, scoreA: 13, scoreB: 9, finished: true }),
});
console.log(res.status, await res.json());

Numbers and booleans can also be sent as strings ("3", "true"). This helps with tools that only send text, like the Stream Deck.

Success

Status 200:

{ "ok": true, "state": { "revision": 42 }, "result": {} }

• state: the part of the HUD state that the command changes, for example { "revision": 42, "vetoVisible": true }.
• result: the data that the command returns. Only some commands return data. See Commands.

Failure

The status is 4xx or 5xx:

{ "ok": false, "error": "conflict", "message": "..." }

See Errors.

GET /api/actions

{
  "ok": true,
  "actions": [
    {
      "id": "set_event_name",
      "description": "Sets the event name shown by the HUD and the SEN scenes.",
      "needsMainWindow": true,
      "payload": {
        "type": "object",
        "properties": { "name": { "type": "string", "maxLength": 120 } },
        "required": ["name"]
      }
    }
  ]
}

• needsMainWindow: true if the command fails when the main MyHUD window is closed.
• payload: the JSON Schema of the payload, or null if the command takes no payload.

Use this route to build a tool that always matches the installed MyHUD version.

GET /api/state

{
  "ok": true,
  "state": {
    "revision": 42,
    "scoreboardVisible": false,
    "vetoVisible": true,
    "statsVisible": false,
    "roster": [{ "slot": 1, "name": "ZywOo" }],
    "hudWindowOpen": true,
    "mainWindowOpen": true,
    "senScene": "versus",
    "obs": { "connection": "connected", "replayBufferActive": true }
  }
}

Field	Description
revision	A number that increases each time the HUD state changes.
scoreboardVisible, vetoVisible, statsVisible	Panels visible on the HUD. Missing until the HUD reports them.
roster	Players by HUD slot (1 to 9, then 0). Use the slot with show_player_stats.
hudWindowOpen	The HUD overlay window is open.
mainWindowOpen	The main MyHUD window is open.
senScene	Scene shown in the scene window, or null if it is closed.
obs.connection	connected, connecting or disconnected.

GET /api/presets

{ "ok": true, "presets": [{ "id": "my-preset", "name": "My preset" }] }

The list is empty until the HUD overlay was opened once.

GET /health

{ "ok": true, "service": "myhud-automation" }

Web pages

For security, a web page open in a browser cannot send commands, even on the MyHUD PC. MyHUD refuses any request that has an Origin header. Only GET /health, GET /api/presets and GET /api/actions accept requests from a web page.

Scripts, Stream Deck, Companion and other programs do not send this header, so they work normally.