# HTTP & WebSocket API

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.

## 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. |

```sh
# 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 }
```

## 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. |

```sh
$ 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 }
  ]
}
```

```json
# 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.

## 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.

```json
# 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.

## 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](https://thermitescada.com/docs/licensing.md)) and, for redundant pairs, the operator actions `POST /api/redundancy/force-resync`, `POST /api/redundancy/request-failover`, and `POST /api/redundancy/assume-control`.

## 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](https://thermitescada.com/docs/security.md).
