Roasthubs v2 API
The v2 API is the typed, OpenAPI-documented HTTP surface built with express-zod-api. Prefer it for new integrations. Legacy routes under /api/... (without v2) still exist but are not covered by this Swagger.
Where to find the docs (Swagger)
On a running Roasthubs instance:
| What | URL |
|---|---|
| Swagger UI | {baseUrl}/api/v2/docs |
| OpenAPI YAML | {baseUrl}/api/v2/docs.yaml |
Examples:
- Local:
http://localhost:\{PORT\}/api/v2/docs - YAML:
http://localhost:\{PORT\}/api/v2/docs.yaml
These doc routes are public (no login required). Calling the actual v2 endpoints normally requires an authenticated session.
The OpenAPI spec is generated at startup from the same routing tree as the live API (src/controllers/v2/v2Router.ts → src/openapi.ts).
Base path
All v2 endpoints live under:
/api/v2/...
Endpoint groups (overview)
| Group | Base path | Purpose |
|---|---|---|
| Health | /api/v2/health | Health check |
| Productions | /api/v2/production | List / create / get / update / delete productions |
| Lots | /api/v2/lots/... | Unload lots / containers (incl. via realisation) |
| Containers | /api/v2/container/:id/emptyToCell | Empty a container into a cell |
| Plant nodes | /api/v2/plantNodes/:id | Update a plant node |
| Zones | /api/v2/roasthubsZones | Zones CRUD-ish + dump lot/container / stop dump |
| Inventory | /api/v2/inventory/inventorizeWeightedCell | Inventorize a weighted cell |
| Dosing | /api/v2/dosing/... | Skip / stop dosing order, flow-alarm empty-cell choice |
| Shrinkage scale | /api/v2/shrinkageScale/discardBatch | Discard a shrinkage-scale batch |
| Scale calibration | /api/v2/scaleCalibration/... | Activate / weights / deactivate / status |
| Connections | /api/v2/connections | External connections + client certificates |
| Production options | /api/v2/productionRealisationOptions, /api/v2/productionTargetOptions | Get/update realisation & target options |
| OPC-UA | /api/v2/opcua/read, /api/v2/opcua/write | Read / write OPC-UA tags |
For request/response schemas and exact methods, use Swagger UI — it is the source of truth.
Auth
- Docs (
/api/v2/docs,/api/v2/docs.yaml): unprotected - Endpoints: require an authenticated user (session), unless a specific route is marked otherwise
Client SDK (frontend)
A TypeScript client is generated from the same routing into:
client/src/express-zod-api-client/v2Client.ts
Use that (or the OpenAPI YAML) when integrating from code.