IO-Darts-Agent: API Documentation

Overview

IO-Darts-Agent exposes a local REST API (Fastify) plus one WebSocket endpoint for real-time events. The API is built for the local network only: it is not designed or hardened for exposure to the public internet.

Two independent protections apply to every route below, in addition to whatever is noted per route:

• Origin check - every request (including the WebSocket upgrade) is rejected with 403 Origin not allowed unless the Origin header is empty (same-origin, curl, etc.) or resolves to a private/local address (127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, link-local, .local/.lan/.home.arpa/.fritz.box, or a dotless hostname).
• CORS mirrors the same local-origin check.

Base URL: http://<hub-host>:3000/api (default port 3000)

Authentication

IO-Darts-Agent has an optional username/password login ("web auth"), configured during setup or in Settings. A single global Fastify hook (onRequest) runs in front of every route below and decides whether the request is even allowed to reach its handler:

• While initial setup is incomplete: only /api/setup/* routes are reachable; everything else returns 403.
• Web auth disabled (default): every route is open to any client on the local network, no login needed.
• Web auth enabled: the request needs a valid autodarts_session cookie (set by POST /api/auth/login), or it must be one of a short, hardcoded list of always-public routes: GET /health, GET /api/auth/session, POST /api/auth/login, GET /api/setup/status. Every other route - including ones marked Public below - returns 401 Authentication required from this global hook before its own code ever runs.

Routes marked Public in the tables below have no additional, route-specific session check in their own handler (so they behave like any other route when web auth is disabled, and some are written as if meant to be reachable without logging in, e.g. for a Game Display or WLED config page opened on a second device). They are still subject to the global hook above, so when web auth is enabled they also require a valid session - this includes the Darts Caller, TTS/Voice Pack, i18n, logs, media file delivery, and module config endpoints. Treat Public here as "no extra per-route check", not as "always reachable without login". Routes marked Session additionally run their own isAuthorized() check and return a 401 body shaped for that route if there is no session.

/api/developer/* additionally requires developerMode: true in the hub settings; it returns 403 otherwise.

REST API

Health

Setup

Authentication

Hub Status & Connection

Settings

Match

Modules

Module UIs are served statically under /module-ui/:moduleId/ (e.g. /module-ui/game-display/), and a module's own custom API routes (registered via the module SDK) are reachable under /api/modules/:moduleId/routes/*; see Module SDK.

Players

Internationalization (hub UI)

AI Providers

The hub ships adapters for elevenlabs, runway, higgsfield, openai, anthropic, stability, ollama, and replicate. All AI routes require a session.

Animation Generator

AI-generated celebration animations (Runway or Higgsfield) for dart events.

Media Library

Stores uploaded/generated animations, sounds, and images used by modules. :type is animation, sound, or image.

Text-to-Speech & Voice Packs

Routes under /api/tts/* have no route-specific session check (Public below). With web auth enabled, the global hook (see Authentication) still requires a session.

Darts Caller

Routes under /api/caller/* have no route-specific session check (Public below). With web auth enabled, the global hook (see Authentication) still requires a session.

Autodarts Trainer

Custom endpoints used by the Autodarts Trainer module.

Session/routine/history data is held in the hub's memory for the current process only; it resets on restart.

Developer Mode

Requires both an authenticated session (if web auth is enabled) and developerMode: true in settings. Used to simulate Autodarts matches without a physical board, for testing modules.

Logs

WebSocket API

Connection

URL: ws://<hub-host>:3000/api/events

Requires a valid autodarts_session cookie if web auth is enabled; the server closes the connection with code 4001 otherwise. There is no separate Server-Sent-Events endpoint - all live data (events, logs, module status, caller requests, voice pack progress) goes over this one WebSocket.

Message Format

All messages are JSON-encoded, each with a type field.

Client to Server

Server to Client

Autodarts Events

event.type is one of a fixed set (AutodartsEventType). Some are forwarded from Autodarts largely unchanged ("native"); others are derived by the hub's EventParser from match.state updates ("synthetic").

Native

Synthetic (derived from match.state)

raw is used for anything the parser doesn't otherwise recognize.

Note on game: match.state, throw.detected, turn.finished, player.change, game.finished, match.finished, match.result, cricket.state, and cricket.closed additionally carry data.game: { variant: string; mode: 'x01' | 'cricket' | 'tactics' | 'other'; cutThroat: boolean }. match.start, match.delete, and match.finish do not carry game.

Note: Individual modules (for example WLED) further derive their own sub-keys - such as throw.triple, throw.double, throw.180, throw.bullseye - from the data inside a throw.detected event, purely for their own per-event action configuration. These sub-keys are not separate events on the bus or the WebSocket; see the module's own README and Module SDK for details.

Error Handling

Most error responses follow this shape, though the exact fields vary by route (some use error, others success: false plus error/message):

{
  "error": "Error message",
  "success": false
}

HTTP Status Codes

Module UI Routing

Modules with their own frontend are served under /module-ui/:moduleId/:

• Game Display: /module-ui/game-display/
• Other modules with a UI follow the same pattern.