Integrate

HTTP API

Everything the UI does is a plain HTTP call, so a host app can drive exuvia headlessly or iframe the UI:

Route
GET /api/projectgraph + per-node status, and every view with its state (?params={...} for one parameter set)
PATCH /api/projectrename, set the timezone
GET /api/params, PUT/DELETE /api/params/{name}run parameters and the values that have run
GET/PUT/DELETE /api/nodes/{name}read / write / delete a node file
GET /api/files, GET/PUT/DELETE /api/files/lib/{path}.pylist / read / write ({"source"}) / delete shared helper modules; each answer names the nodes that import the file (used_by). Paths outside lib/, other extensions and .. are rejected (400)
GET /api/viewsevery view with its state (?params=), as in /api/project
GET/PUT/DELETE /api/views/{name}one view with its parsed manifest and every file's source / create it or replace its view.json (body: the manifest) / delete the folder
GET/PUT/DELETE /api/views/{name}/files/{path}read / write ({"source"}) / delete one file of a view (App.tsx, components/Chart.tsx). Paths outside the view folder, .., absolute paths and other extensions are rejected (400); writes return the view
POST /api/views/{name}/restoremake a saved version ({path, hash}) of one view file current again; brings back a deleted file or view
GET /api/views/{name}/data/{node}/api/nodes/{node}/data for a view: 403 unless the view's reads lists node
POST /api/views/{name}/query/api/query for a view: only the nodes in its reads exist, and the connection cannot open other files (see "Rendering a view")
POST /api/nodescreate from a template
POST /api/nodes/{name}/runrun a node; {"wait": seconds} waits and returns the same report the agent's run_node gets (status, error + log tail, or schema, rows and first rows; running: true if still going)
POST /api/runbring the graph (or named nodes) up to date for a parameter set (wait as above: per-node status and each failure's error + log tail)
GET /api/guidethe agent's instructions for this project (conventions, parameters, project notes) and its tool list, for an outside agent writing nodes over HTTP
POST /api/run-stalerefresh everything stale
POST/GET/DELETE /api/backfillreplay a list or date range of parameter values
GET /api/nodes/{name}/dataa node's output (?params= or ?run_id=, ?limit=, ?offset=): JSON rows, or an Arrow stream (see "Binary data")
GET/HEAD /api/artifacts/{node}/{artifact_id}.parquet (or .json)the stored file of one output, byte for byte, with Range support (see "Binary data")
GET /api/nodes/{name}/historythe node's stored output per parameter set (with the code_hash each was computed with)
GET /api/code/revisionssaved versions of the code, newest first (?node= for one node, ?view= for one view's files, deleted ones included); each says who saved it and whether it is current
GET /api/code/blobs/{hash}the text of one saved version
POST /api/nodes/{name}/restoremake a saved version ({hash}) current again; brings back a deleted node
GET /api/runs/{run_id}/sourcethe exact code a run executed
POST /api/queryDuckDB SQL over all outputs ({sql, limit, params}): JSON rows, or an Arrow stream (see "Binary data")
POST /api/nodes/{name}/scheduleset, clear, pause or resume a schedule
POST /api/schedule/tickevaluate schedules now (for external schedulers)
GET /api/eventsSSE: graph changes, run status, live logs
POST /api/agentSSE: agent turn
GET/DELETE /api/agent/{session_id}, POST .../cancelsaved transcript, clear it, stop a turn

Requests that change code may send X-Exuvia-Origin (letters, digits, -, _; e.g. ui or mcp) to label the revisions they create; otherwise they are recorded as api.

Binary data: Arrow and Parquet

The JSON answers of /api/query and /api/nodes/{name}/data are for previews: values become text or floats, and at most 5,000 rows come back (500 and 200 unless limit says otherwise). A client that wants the data itself has two other ways to read it.

Arrow stream. Send Accept: application/vnd.apache.arrow.stream to either route and the answer is an Arrow IPC stream: typed columns, every row unless limit is given, written batch by batch.

import { tableFromIPC } from "apache-arrow";

const res = await fetch("/api/query", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/vnd.apache.arrow.stream" },
  body: JSON.stringify({ sql: "select * from rolling_vol where ticker = 'AAPL'" }),
});
const table = tableFromIPC(new Uint8Array(await res.arrayBuffer()));
JSON.parse(table.schema.metadata.get("exuvia")); // { columns: [{ name, type }] }
  • The schema metadata key exuvia holds, as JSON, what the JSON answer has besides the rows: columns (names and DuckDB types) and, for a node's output, kind, total, run_id, run_params and finished_at.
  • A statement that fails is answered with the usual 400 JSON error. One that fails after its first batch has been sent ends the stream early, which an Arrow reader reports as a truncated stream.
  • On /api/nodes/{name}/data, an output that is not a table (a JSON value, or no output yet) is answered as JSON whatever Accept says, so send Accept: application/vnd.apache.arrow.stream, application/json and look at the response's Content-Type.
  • Buffers are not compressed, so any Arrow library can read the stream.

The stored file. Every output is a file named after its content: artifact_id in /api/project and /api/nodes/{name}/history, with output_kind / kind saying whether it is a table (.parquet) or a JSON value (.json). GET /api/artifacts/{node}/{artifact_id}.parquet returns that file as it is stored, downloading it from EXUVIA_ARTIFACT_STORE first when this process does not have it.

  • The answer for a given URL never changes, so it is sent with Cache-Control: private, max-age=31536000, immutable and the artifact id as its ETag.
  • Range requests are honoured (206, Accept-Ranges: bytes) and HEAD gives the size, which is all a Parquet reader that fetches only the footer and the columns it needs (DuckDB, DuckDB-Wasm, pyarrow) asks for.
  • Outputs of earlier runs and other parameter sets stay readable for as long as the project exists; an id no successful run produced is a 404.

Set EXUVIA_CORS_ORIGINS for cross-origin hosts. exuvia.connectors.lobster queries the Lobster lake from any node (LOBSTER_API for the base URL; LOBSTER_TOKEN is sent as a bearer token when set and omitted otherwise, for hosts that attach credentials at the network edge).