The HTTP API¶

The API covers the same operations as the browser. Use it for scripts, integrations, or your own client.

Set the base URL for your instance:

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

Use the port printed by fluksio serve. For Docker, use http://localhost:8080/api/v1, or https://<your-domain>/api/v1 for a deployment. All paths below are relative to this base. Timestamps in responses are ISO 8601 and always carry their UTC offset.

Authenticating¶

fluksio serve signs the local CLI in automatically. To reuse its token from a project instance, with jq installed:

export TOKEN=$(jq -r .token .fluksio/client.json)

Adjust the path for --global or --data-dir. For a remote instance, use its login endpoint with the administrator credentials:

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

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

Session tokens last eight days by default. POST /login/test-token checks a token. Password recovery uses POST /password-recovery/{email} and POST /reset-password/.

Agents over MCP use separate OAuth tokens.

Flows¶

Deleting a flow keeps its run history. Delete runs separately.

Node source¶

curl "$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"}'

Writing code requires a superuser. So does adding, retyping, or repointing Function and Command nodes, changing Command settings, or changing resources.env. Other users can edit wiring, titles, and ordinary settings.

Ordinary source edits stay in the draft until publishing. Shared library source changes affect its users immediately, and the audit trail records them like a publish. POST /flows/{name}/nodes/{id}/share promotes a source to the library; /unshare makes it private again. GET /flows/library lists shared sources. DELETE /flows/library/{name} retires one, and answers 409 while nodes still use it. With ?detach=true each of those nodes keeps a copy of the code, in the published flow and the draft, and the shared source is deleted.

Running and controlling¶

A preview run can have real side effects. On a batch flow, /run submits a recorded run; use the run endpoints below for parameters and tracking.

Messages¶

curl "$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 "$FLUKSIO/messages/house.temperature/history" \
  -H "Authorization: Bearer $TOKEN"

The catalogue contains messages declared by published flows and their last values. You can publish only to declared messages, just as dashboard controls do.

Runs¶

Submissions return a queued run immediately. Invalid or undeclared parameters return 422 before execution. Optional draft and no_cache flags select unpublished code or skip stage caching.

History filters include flow, status, group, digest, since, before, limit, and offset. Rows arrive newest first; use the last row's created_at as before for stable pagination.

A node's outputs come from the stage cache, so only a node that succeeded and may be cached has them, up to 256 kB of JSON. Any other node answers 404.

Exports also accept ids and until, with format=csv or jsonl. The metrics export is a long table; the runs export is one row per run. Use params and metrics to choose columns, including dotted paths into record outputs. An export covers at most the newest 10 000 runs. When a selection matches more, the response carries X-Truncated with that cap and X-Total-Count with the number of runs the selection matched.

Import takes {"runs": [...]}, records completed results without executing code, and deduplicates by external_id. See Runs for examples, artifacts, caching, and exports.

Artifacts¶

curl -X PUT "$FLUKSIO/artifacts?name=model.pt" \
  -H "Authorization: Bearer $TOKEN" --data-binary @model.pt
curl "$FLUKSIO/artifacts/<digest>" \
  -H "Authorization: Bearer $TOKEN" -o model.pt

The upload returns a reference with the content digest. Identical bytes are stored once. Node code uses save_artifact and load_artifact instead. ?volatile=true holds the bytes in the engine's memory for a live frame, where newer frames push them out, instead of storing them.

A superuser can remove stored bytes with DELETE /artifacts/<digest>. While a run, a current message or a flow input's initial value still references the digest, the call returns 409. The hourly sweep removes unreferenced bytes on its own, so this is for reclaiming space sooner.

Dashboards and devices¶

/panels/pair, /panels/pair/{code} and GET /panels/{id} answer as their /devices/ counterparts, for firmware that has not updated yet.

Secrets, modules, and alerts¶

Secrets and package changes require a superuser. Applying a manifest replaces the whole managed environment's package list. Adopted environments are read-only here; install their packages yourself.

Connector state keys can also be listed and cleared by a superuser; see the connector contract.

Observability and workers¶

Changing flavors requires a superuser. See Remote workers.

Live events¶

Connect to ws://127.0.0.1:8000/api/v1/flows/ws with an Authorization: Bearer <access-token> header.

Browsers first call POST /flows/ws-ticket, then connect with ?ticket=<ticket>. Tickets are single-use and expire after 30 seconds. The socket sends a snapshot followed by node, value, health, and run events.

A client asks for the bytes of the media it shows with {"type": "media", "names": [...]}, which replaces what it asked for before, for at most 8 messages. Each frame held in memory then arrives as a binary message before the value naming it: four bytes of header length (big endian), a JSON header {"type": "media", "name", "digest", "media_type", "ts"}, then the bytes. Messages are sent without per-message compression.

A device's socket is bounded to its own messages. Its snapshot carries "demand", the ports it reported as on_demand that someone wants now, and "uplink", "binary" on its own socket and "http" through the portal. When that set changes it is sent {"type": "demand", "ports": [...]}. A port has demand while a socket asks for the media of the message it is wired to, or a node of a running flow reads that message.

With a binary uplink the device sends a camera frame as a binary message in the same layout, with the header {"type": "frame", "name": "<message>", "media_type": "image/jpeg", "ts": <device ms>}. The message has to be one of its in ports wired as image. The frame is held in memory and published in one step, credited to its device node. A frame that does not qualify is logged and dropped and the socket stays open. With http it uploads with PUT /artifacts?volatile=true&name=<message> and publishes with POST /messages/<message>. A device that is unpaired or deleted while connected is closed with 1008.

Errors and client generation¶

For a version conflict, read current_version, reload, merge your edits, and save again. Other 409 responses describe their own conflict.

make generate-client regenerates the frontend SDK. To generate a client in another language, use the instance's /api/v1/openapi.json schema.