REST API Reference

Ciaren is a FastAPI service. The visual editor is built entirely on this REST API, and you can drive every feature with it directly. All endpoints are served under http://localhost:8055 by default.

Resources

Each resource has its own reference page:

• Projects — workspaces grouping datasets and flows
• Datasets — upload and inspect versioned source files
• Flows — saved pipelines (graph), preview, and code export
• Runs — execute flows and read status, logs, per-node results, SSE stream
• Transformations — list node types, preview one node
• Catalog & Plugins — backend-fed node catalog and installed-plugin introspection
• Schedules — run flows automatically on a cron schedule
• Connections — reusable database connections for SQL nodes
• Settings — read and override the runtime-editable server settings
• ML endpoints — model metrics, registration, aliases, experiments, and runs under /api/ml/*, /api/runs/{id}/ml/*, and /api/flows/{id}/ml/*
• Marketplace — plugin Explore catalog and install endpoint under /api/marketplace

Webhook trigger

POST /api/flows/{flow_id}/trigger starts a run authenticated by a pre-shared secret (CIAREN_WEBHOOK_SECRET). Designed for CI/CD pipelines and external orchestrators. See the Webhook guide for full details.

Conventions

• Base URL: http://localhost:8055 (configurable via --host/--port).
• Format: JSON request and response bodies; POST /api/datasets/upload uses multipart form data.
• IDs: path parameters like {flow_id} are the resource's id.
• Health check: GET /health (liveness) returns {"status": "ok"} — the process is up, no dependencies checked.
• Readiness check: GET /ready verifies the database is reachable. Returns 200 {"status": "ok", "database": "up"} when ready, or 503 {"status": "unavailable", "database": "down"} so a load balancer drains the instance.
• Optional API auth: when CIAREN_API_TOKEN is set, /api/* requests must send Authorization: Bearer <token> or X-Ciaren-Token: <token>. Static UI, /health, /ready, OpenAPI docs, and the webhook trigger's own secret are exempt. Browser clients may use either header; CORS preflight allows X-Ciaren-Token. The bundled web UI keeps the token in memory and sessionStorage only (never localStorage): it is cleared when the browser session ends and is not inherited by the next user of a shared machine. You can seed it once from a bookmarked …/?api_token=<token> URL, which the UI strips from the address bar. Sending the token as a header (rather than a cookie) is deliberate — it is what defeats cross-site (CSRF) requests, since a browser can't attach a custom header cross-site without a preflight the token gate would reject.
• Browser origin guard: without an API token, state-changing (POST/PUT/ PATCH/DELETE) /api/* requests that carry a browser Origin header are refused (403) unless the origin is in CIAREN_CORS_ORIGINS or its hostname is local (localhost, 127.0.0.1, ::1) or listed in CIAREN_TRUSTED_HOSTS. This blocks CSRF/DNS-rebinding against a local, unauthenticated instance; clients that send no Origin (curl, scripts, server-to-server) are unaffected. See Local-first trust model.

Typical workflow

1. POST /api/datasets/upload — upload a CSV/TSV/Excel/Parquet/JSON/text file.
2. POST /api/flows — save a graph that reads the dataset and applies nodes.
3. POST /api/flows/{id}/preview — check the result on sample data.
4. POST /api/flows/{id}/runs — run the full pipeline.
5. GET /api/runs/{run_id} — poll status and read logs.
6. GET /api/runs/{run_id}/logs/stream — stream logs as SSE (optional).
7. POST /api/flows/{id}/export/python — get standalone code (pandas and polars).

See Also

• Transformations Reference — every node and its config
• Webhook Trigger — trigger runs from CI/CD or Airflow
• Python SDK — typed Python client for the API
• Installation — get the backend running