API Reference

RondoFlow’s backend is a Fastify server that exposes a REST API under the /api base path. The drag-and-drop Workspace (Canvas) UI talks to it over plain HTTP, while live execution events stream separately over Socket.IO. This page documents the HTTP surface: conventions, authentication, and a catalog of every route grouped by resource.

Conventions

Base path

Every endpoint is mounted under /api. There is no version prefix.

Response envelope

All responses use a single consistent envelope, so the UI never has to parse Fastify’s default error shape:

{
  success: boolean
  data?: unknown      // present on success
  error?: string      // present on failure
  meta?: {            // present on paginated lists
    total: number
    page: number
    limit: number
  }
}

• Success responses set success: true and put the payload in data. Created resources return 201; accepted-but-async actions (loops, chains, pipelines) return 202.
• Failure responses set success: false and put a human-readable string in error. This holds even for uncaught throws, body-parse failures, and unknown paths — the global error and not-found handlers guarantee the envelope.

Common status codes:

Input validation

Request bodies and query strings are validated with Zod  at the route boundary. Invalid input returns 400 with a message describing the offending field(s). UUID path params are checked against a UUID pattern before any database call on several resources (resources, workspace memories).

Authentication

The API uses cookie/session authentication powered by Better Auth . Sign-in and OAuth callbacks are handled under /api/auth/*. A preHandler hook validates the session cookie on every non-public route; if there is no valid session it returns 401 with { success: false, error: "Authentication required" }. A second preHandler then applies a default-deny role gate to the authenticated request (see Role-based authorization).

Public (no-auth) paths:

Because auth relies on cookies, browser requests must send credentials. CORS is locked to the UI origin (UI_ORIGIN, default http://localhost:3000) with credentials: true, and allows the GET, POST, PUT, PATCH, DELETE, OPTIONS methods. Socket.IO connections are authenticated the same way — the session cookie is validated on the handshake.

// Cookies are sent automatically when credentials are included.
const res = await fetch('http://localhost:3001/api/agents', {
  credentials: 'include',
})
const { success, data } = await res.json()

# -b/-c persist the session cookie established by sign-in.
curl -s http://localhost:3001/api/agents \
  -b cookies.txt -c cookies.txt

Role-based authorization

RondoFlow is a single shared team Workspace, not a multi-tenant system: every authenticated user sees the same pool of resources. Access is gated by role, not by per-user ownership. userId columns are retained for attribution and audit only, not for data isolation.

There are three ranked global roles — viewer < editor < admin:

• viewer — read-only. Can list and read everything, but cannot create, edit, delete, or run anything.
• editor — adds the write and run capabilities: create/edit/delete resources and run workflows, Assistants, chains, discussions, loops, emails, and the Director/Planner/Advisor.
• admin — adds manageUsers and manageGlobalSettings: user management and the global credential settings surface.

New accounts default to viewer (fail-closed). Enforcement is a default-deny preHandler keyed on HTTP method + path:

• Paths under /api/users and /api/settings/credentials are admin-only for any method, including GET — they are the default-deny ADMIN_PREFIXES, gated by the manageUsers capability.
• Reads (GET/HEAD/OPTIONS) on every other route are open to any authenticated user (viewer and up).
• Mutating run actions — paths matching start/stop/pause/resume/run-now/execute — require editor (run).
• Any other POST/PUT/PATCH/DELETE requires editor (write).

Because the gate is default-deny, a newly added mutating route is protected automatically. A request whose role lacks the required capability returns 403. Socket.IO mirrors this — viewers are read-only there too. See Security Model.

Rate limits

Rate limiting is global and keyed by client IP. The default ceiling is generous so the polling UI is unaffected; a few abuse-prone routes set tighter per-route limits.

Exceeding a limit returns 429 with a "Rate limit exceeded — retry in Ns" message.

Health check

GET /api/health

Returns { status, timestamp, prerequisites, engine } where engine reports runningAgents, queuedAgents, and pendingApprovals. Along with /api/auth/* and /api/auth-providers, this is one of the few endpoints reachable without a session.

Endpoint catalog

The sections below list every resource and its endpoints. Path params are written :name; query params are noted in the purpose column.

Auth

Handled by Better Auth. The catch-all route below proxies all auth traffic (sign-in, sign-up, OAuth providers, session lookup). See Configuration for enabling GitHub/Google OAuth.

Assistants (agents)

Assistants are the core executable unit. See Assistants.

On create, provider is one of claude-code, openai, or perplexity; openai/perplexity Assistants must include a providerConfig. See Providers.

Assistant skills (subresource)

Assistant memories (subresource)

See Memory.

Assistant connections (MCP subresource)

See Connections.

Assistant external folders (subresource)

See External Folders.

Assistant loops (subresource)

See Loops.

Workspaces & Canvas

A Workspace (Canvas) holds the visual layout of Cards and edges. See Canvas.

Canvas transfer (export / import)

Share a whole Workspace as a self-contained bundle. See Connections and Canvas.

Workspace resources (subresource)

See Resources.

Workspace memories (subresource)

See Memory.

Runs

Historical workflow/chain executions, with token and cost rollups. See Monitoring.

Datasets

Structured datasets produced by the Structure (Structurer) → Save to DB Card pipeline on the Canvas. A Save-to-DB step persists a typed dataset (schema + rows) to the StructuredDataset/StructuredRow tables; these read-only endpoints back the Saved Datasets panel and its CSV export. See Data Nodes.

Skills

Built-in catalog, git installs, and custom Skills. See Skills.

Safety Rules (policies)

Policies that constrain what an Assistant may do. Resolution is most-restrictive-wins. See Safety Rules.

Discussions

Multi-Assistant discussions run by a Facilitator (Moderator). See Discussions.

Participants (subresource)

Schedules

Cron-based recurring runs of a workflow or Assistant. See Schedules.

Conversations (sessions)

Records of Assistant/discussion runs and their messages. See Monitoring.

Connections (MCP servers)

Registry of external MCP servers. See Connections. Per-Assistant assignment lives under the Assistant connections subresource above.

External folders

Mounted host directories an Assistant may access. See External Folders. Per-Assistant attachment lives under the Assistant external folders subresource above.

Activity

Filterable audit log. See Monitoring.

Analytics

Token and cost aggregation. See Monitoring.

Git

Run git operations against a Workspace’s working directory. See Git. Reads are open to any authenticated user; write operations (stage, commit, push, branch, checkout) require the run/write capability (editor+) and act on the Workspace’s configured working directory.

Approvals

Pending tool-permission requests raised mid-run. See Safety Rules. Approvals also stream over Socket.IO and auto-reject on timeout.

Users (admin)

Admin-only user management for the shared Workspace. Every route requires the admin role (the manageUsers capability); the entire /api/users prefix is one of the default-deny ADMIN_PREFIXES. These routes wrap the Better Auth admin plugin and record each action to the audit log. See Security Model.

Audit events emitted: user_invited, user_role_changed, user_deactivated, user_reactivated, user_deleted.

Settings & credentials

Provider/OAuth/SMTP credentials and the global budget cap. See Settings and Configuration.

The /api/settings/credentials prefix is admin-only — it is one of the default-deny ADMIN_PREFIXES (the manageUsers capability), so every method, including GET, requires admin. The budget endpoints sit outside that prefix and follow the generic gate: GET is open to any authenticated user, and PUT needs the write capability (editor+). The public GET /api/auth-providers lives in this route file too.

For each credential field: omit to leave unchanged, send "" to clear (restoring the .env fallback), or send a value to set it. Managed keys include anthropicApiKey, claudeCodeOauthToken, openaiApiKey, perplexityApiKey, the GitHub/Google OAuth client ID/secret pairs, and the SMTP fields (smtpHost, smtpPort, smtpSecure, smtpUser, smtpPass, smtpFrom) that power the Email Card.

Email

Send a workflow’s combined Assistant output as an HTML email via SMTP — the REST surface behind the Email Card on the Canvas. See Data Nodes.

POST /api/email/send collapses CR/LF in the subject (header-injection defense) and validates every recipient address server-side. When SMTP is not configured it returns 400 with "Email is not configured. Set SMTP_HOST and SMTP_FROM."; when the SMTP server refuses delivery it returns 502 with code EMAIL_SEND_FAILED.

Workflow generation

AI-generated multi-Assistant workflows from a task description. See Workflows.

Saved workflows

Reusable, named workflow definitions. See Workflows.

Chains & PRDs

DAG execution and the PRD-to-stories pipeline. See Orchestration.

Claude CLI status

Probe Claude API connectivity and auth — drives the Start (Spawn) Card’s Test button and the pre-run gate. See Claude Code provider.

Filesystem

Browse the host filesystem and read/write workflow output files (path-traversal guarded). These back the Output Card’s destination-directory picker and “Open saved file” affordance. See Data Nodes.

Related