Ciaren

REST API Reference

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.

Interactive docs

Run the backend and open http://localhost:8055/docs for the live Swagger UI, or http://localhost:8055/redoc for ReDoc. Both are generated from the running app, so they always match your version.

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.

MethodPathDescription
GET/api/settings/webhookReturns {"configured": true/false} (never the secret)
POST/api/flows/{flow_id}/triggerTrigger a run; requires X-Ciaren-Secret header

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

NextProjects API