The HTTP API¶

Everything the browser does, the API does first. The dashboard is a generated client of this schema, not a privileged path into the engine — so anything you can click, you can script.

Base URL: https://api.${DOMAIN}/api/v1, or http://127.0.0.1:8000/api/v1 for a fluksio serve installation.

export FLUKSIO=http://127.0.0.1:8000/api/v1

Authenticating¶

export TOKEN=$(curl -s -X POST $FLUKSIO/login/access-token \
  -d "username=admin@example.com&password=..." | jq -r .access_token)

curl -s $FLUKSIO/users/me -H "Authorization: Bearer $TOKEN"

A bearer token, valid for eight days. POST /login/test-token checks one. Password recovery and reset are POST /password-recovery/{email} and POST /reset-password/.

Agents authenticate differently — see Agents over MCP.

Flows¶

Reading a flow returns the draft when one exists, along with a preview of how it would run: node statuses and validation issues for the version you are editing, not the one running underneath it.

Node source¶

curl -s $FLUKSIO/flows/house/nodes/decide/source -H "Authorization: Bearer $TOKEN"
curl -X PUT $FLUKSIO/flows/house/nodes/decide/source -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"code": "def process(x):\n    return {\"y\": x * 2}\n"}'

POST .../share promotes a node's source to the shared library; POST .../unshare gives it a private copy back. GET /flows/library lists the shared sources and which flows use each.

Running and controlling¶

POST /flows/{name}/run on a batch flow submits a run instead, because that is what running one means — the parameters, the series and the result are the point, and a call that quietly did something else would be a trap.

Messages¶

curl -s $FLUKSIO/messages/ -H "Authorization: Bearer $TOKEN"
curl -X POST $FLUKSIO/messages/house.setpoint -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"value": 22.5}'
curl -s $FLUKSIO/messages/house.temperature/history -H "Authorization: Bearer $TOKEN"

GET /messages/ is the catalogue: every message any published flow declares, with its last value. Publishing puts a value into the graph exactly as a dashboard control does — which means only a message some flow declares can be published to. Flows own the namespace; everything else is a client of it.

Runs¶

Submitting answers immediately with a queued run. Wrong parameters — an undeclared name, a value of the wrong type — come back as a 422 naming the problem, before anything executes.

?digest= filters by the hash of the parameters, which is how you find "every run that used exactly this configuration".

compare answers in the same shape a chart widget draws, so three training curves side by side is a widget binding rather than a screen of its own.

See Runs: pipelines that finish.

Artifacts¶

curl -X PUT $FLUKSIO/artifacts -H "Authorization: Bearer $TOKEN" \
  --data-binary @model.pt
curl -s $FLUKSIO/artifacts/sha256:abc... -H "Authorization: Bearer $TOKEN" -o model.pt

Content-addressed, so uploading the same bytes twice stores them once. Node code normally reaches these through fluksio.save_artifact / fluksio.load_artifact rather than here.

Dashboards and panels¶

Secrets, modules, alerts¶

curl -s $FLUKSIO/secrets/ -H "Authorization: Bearer $TOKEN"          # names only
curl -X PUT $FLUKSIO/secrets/influx-token -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"value": "..."}'

curl -s $FLUKSIO/modules/ -H "Authorization: Bearer $TOKEN"
curl -X POST $FLUKSIO/modules/apply -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"requirements": "numpy>=2\n"}'

curl -s $FLUKSIO/alerts/config -H "Authorization: Bearer $TOKEN"
curl -X POST $FLUKSIO/alerts/test/my-phone -H "Authorization: Bearer $TOKEN"

Secrets are write-only over the API: you can list names and set values, never read one back.

Observability¶

GET /utils/health/ is the deep health check the container probe uses: it fails when the event loop is wedged or the state backend is gone, not just when the process is dead.

Workers¶

See Remote workers.

Live events¶

ws://127.0.0.1:8000/api/v1/flows/ws?token=<access token>

The websocket authenticates from its query string. It sends a snapshot on connect and then every engine event: node executions, values published, health changes, run started and finished. This is what the canvas and the dashboards draw from.

Errors¶

A 409 on a save or a publish is not an error to retry blindly: it means the stored version moved past the one you were editing. Re-read, merge, save again.

Generating a client¶

The frontend's TypeScript client is generated from the OpenAPI schema (make generate-client). Any OpenAPI generator will do the same for your language — point it at /api/v1/openapi.json on a non-production installation.