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/project | graph + per-node status, and every view with its state (?params={...} for one parameter set) |
PATCH /api/project | rename, 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}.py | list / 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/views | every 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}/restore | make 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/nodes | create from a template |
POST /api/nodes/{name}/run | run 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/run | bring 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/guide | the 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-stale | refresh everything stale |
POST/GET/DELETE /api/backfill | replay a list or date range of parameter values |
GET /api/nodes/{name}/data | a 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}/history | the node's stored output per parameter set (with the code_hash each was computed with) |
GET /api/code/revisions | saved 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}/restore | make a saved version ({hash}) current again; brings back a deleted node |
GET /api/runs/{run_id}/source | the exact code a run executed |
POST /api/query | DuckDB SQL over all outputs ({sql, limit, params}): JSON rows, or an Arrow stream (see "Binary data") |
POST /api/nodes/{name}/schedule | set, clear, pause or resume a schedule |
POST /api/schedule/tick | evaluate schedules now (for external schedulers) |
GET /api/events | SSE: graph changes, run status, live logs |
POST /api/agent | SSE: agent turn |
GET/DELETE /api/agent/{session_id}, POST .../cancel | saved 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
exuviaholds, 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_paramsandfinished_at. - A statement that fails is answered with the usual
400JSON 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 whateverAcceptsays, so sendAccept: application/vnd.apache.arrow.stream, application/jsonand look at the response'sContent-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, immutableand the artifact id as itsETag. Rangerequests are honoured (206,Accept-Ranges: bytes) andHEADgives 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).