Skip to content
Thermite SCADA
Docs · Operate

HTTP & WebSocket API

View as Markdown

Production projects use /p/<slug>/ and can add a dedicated port; drafts use /draft/<slug>/<name>/. Each has scoped tags, history, screens, and WebSocket routes. The gateway carries the admin API. Authentication is off by default; when enabled it uses cookie sessions and CSRF tokens.

Project API

Under /p/<slug>/ — or /draft/<slug>/<name>/.

Method
Path
Notes
GET
/api/status
Project status. With authentication enabled, requires a project session, including a configured anonymous session.
GET
/healthz
Bare liveness — returns "ok". Always public; point probes here.
GET
/api/tags
Browse the project's tag tree from the root.
GET
/api/tags/{path}
Read one tag (value, quality, timestamp), or browse if {path} is a folder.
PUT
/api/tags/{path}
Write a tag. Body {"value": …}, coerced to the declared data_type. With authentication enabled, requires can_write_tags.
GET
/api/history/{path}
Historical series — parameters below. With authentication enabled, requires can_read_history.
WS
/api/ws/tags
Live tag subscription stream — protocol below.
POST
/api/ws-ticket
Single-use WebSocket upgrade ticket (needed when auth is on).
GET
/hmi/{screen}/
The project's HMI screens.
# read
$ curl http://localhost:8400/p/press-line/api/tags/press/outputs/HeadPressure
{
  "type": "tag",
  "path": "press/outputs/HeadPressure",
  "value": { "value": 86.6, "quality": "good", "timestamp": "2026-07-03T18:40:12.314028500Z" }
}

# write — value is coerced to the tag's declared type
$ curl -X PUT http://localhost:8400/p/press-line/api/tags/press/recipe/TargetPressure \
    -H "Content-Type: application/json" -d '{"value": 1850.0}'
{ "ok": true }
History

GET /api/history/{path}

Param
Meaning
start
Required. ISO 8601 (2026-07-01T00:00:00Z) or relative: -30m, -1h, -7d.
end
Optional; defaults to now.
mode
raw (default) or aggregated.
interval
Required for aggregated — 1m, 5m, 1h, 1d…
limit
Max points; default 10 000, capped at 100 000.
$ curl "http://localhost:8400/p/press-line/api/history/press/outputs/HeadPressure?start=-1h&mode=aggregated&interval=5m"
{
  "mode": "aggregated",
  "tag": "press/outputs/HeadPressure",
  "interval_seconds": 300,
  "count": 1,
  "points": [
    { "interval_start": "2026-07-03T17:40:00Z", "avg": 42.1, "min": -98.4, "max": 99.7, "count": 600, "first": 12.9, "last": 55.0 }
  ]
}
# mode=raw (the default)
{
  "mode": "raw",
  "tag": "press/outputs/HeadPressure",
  "count": 2,
  "points": [
    { "timestamp": "2026-07-03T18:40:12.314Z", "value": 86.6, "quality": "good" },
    { "timestamp": "2026-07-03T18:40:12.814Z", "value": 87.1, "quality": "good" }
  ]
}

Aggregation buckets are computed at query time in PostgreSQL — no rollup jobs.

WebSocket

Live subscriptions.

Connect to the project's /api/ws/tags. With auth on, first fetch a single-use ticket (POST /api/ws-ticket) and pass it as ?ticket=… on the upgrade. thermite.js does all of this for screens.

# client → server
{ "type": "subscribe", "tags": ["press/outputs/HeadPressure", "press/outputs/CycleActive"] }
{ "type": "unsubscribe", "tags": ["press/outputs/CycleActive"] }

# server → client
{ "type": "update", "values": { "press/outputs/HeadPressure": { "value": 87.1, "quality": "good", "timestamp": "2026-07-03T18:40:12.814Z" } } }
{ "type": "resync", "values": { "press/outputs/HeadPressure": { "value": 87.1, "quality": "good", "timestamp": "2026-07-03T18:40:12.814Z" } } }
{ "type": "snapshot_changed", "snapshot_id": "snap-01a1d097bbd6…" }
{ "type": "error", "message": "…" }

snapshot_changed tells connected clients the project was republished — screens use it to prompt or reload.

Admin API

On the gateway port.

Method
Path
Notes
GET
/api/status
Gateway status. Public — includes the mesh TLS fingerprint peers pin.
GET
/api/license/status
License and trial state. Public — returns 200 even unlicensed; probe the state field.
GET
/api/devices
Configured devices with connection state.
GET
/api/databases
Configured database connections.
GET
/api/queries
Named queries across the site.
POST
/api/queries/{name}/execute
Run a named query: body {"parameters": {…}} → {query, row_count, rows}.
GET
/api/transactions
Transaction group statuses.
GET
/api/audit
The audit log records write outcomes with actor, project, and tag context.
GET
/api/logs
Recent gateway log lines (the in-memory buffer).
GET
/api/redundancy/status
Redundant-pair role, sync, peer, and fencing state — standalone shape when unpaired.

Plus the license endpoints (apply, activate, trial/start, request-file — see Licensing & trial) and, for redundant pairs, the operator actions POST /api/redundancy/force-resync, POST /api/redundancy/request-failover, and POST /api/redundancy/assume-control.

Auth

Cookie sessions and CSRF.

  • Authenticate with POST /login (form fields username, password); the session is an HttpOnly cookie, scoped to the gateway or to one project.
  • With authentication enabled, protected state-changing requests need the session's CSRF cookie and matching X-CSRF-Token header. Login and logout are exempt.
  • With authentication enabled, public gateway routes are /login, /logout, GET /api/status, GET /api/license/status, GET /favicon.ico, and /hmi/thermite.js / /hmi/thermite.css when HMI serving is enabled. GET / and GET /portal/logo are public when the portal is enabled. Public GET branding assets: /admin/logo and /admin/assets/ followed by base.css, theme.css, roboto.ttf, or roboto-mono.ttf. Project public paths: /login, /logout, /healthz, /branding/*, /hmi/thermite.js, and /hmi/thermite.css. Project /api/status, screens, and data require a project session; anonymous_role can grant restricted anonymous access.
  • Authentication is off by default; session and role checks are bypassed. The audit log records write outcomes.

Full auth model: Users, roles & security.