API documentation

This page maps every programmatic surface the platform exposes. Each one links to its own detailed documentation.

Generated code reference

Two generated, code-level API references accompany the hand-written docs:

TypeScript API is the full @flow/shared-types reference. It covers every interface, type alias, function, and guard. TypeDoc generates it on every site build, and you can browse it under Development → TypeScript API in the sidebar.
Rust API is the rustdoc for all workspace crates. flow_application is the orchestrator entry point, and flow_domain, flow_execution, flow_dsl, the adapters, and the rest are one click away. Regenerate it with pnpm site:rustdoc from the repo root. That command runs cargo doc --workspace --no-deps and publishes the output with the site.

The HTTP/SSE API (Flow Server)

This is the canonical remote API. It covers templates, history, the node catalog, and managed-model control. It also includes POST /api/run, which accepts a graph, a template slug, or raw DSL and streams execution events as server-sent events. The API is gated by an optional bearer token. Full route reference.

curl -N localhost:8787/api/run -H 'content-type: application/json' \
  -d '{"template":"hello-flow"}'

The invoke bridge

POST /api/invoke takes {command, args} and exposes the same command surface the desktop shell registers, including settings, hubs, schedules, templates, and the rest. It returns each core type verbatim. This is the seam the host facade uses, and it is the one external tooling can use to drive an instance programmatically. Unwired commands return 501.

The execution event stream

One event vocabulary crosses every surface. The same tagged execution-event union is:

emitted to the desktop UI over the flow:execution event channel,
streamed by the server as SSE data: frames, and
printed by the CLI as NDJSON (one event per line, capped with a final summary line) under --json.

flow run flow.flow --json | jq 'select(.kind=="summary")'

Events cover run lifecycle, per-node status transitions, streamed node logs, LLM token deltas, tool-call steps, confirmation pauses, and the terminal summary. Exit codes for CI gating are documented in CI integration.

Frontend/core event channels

Beyond flow:execution, three channels serve the model-management UI. The first is models:install_progress, which carries {stage, current, total, message} for downloads and engine fetches. The second is models:registered, which carries a model id from the boot scan. The third is models:scan_complete. By convention, all command invocations are consolidated in the frontend’s services layer, and components never call the backend directly.

The AI node API

The ai node has a full field surface that includes provider, modelId, input, system, sampling parameters, task, tools, labels, expect, outputSchema, auditContent, and failover fields. It is documented per provider class:

AI overview covers the capabilities and the common contract.
Cloud providers covers the node configuration table, credential resolution, and privacy defaults. The internal dispatch path lives in flow-execution.
DSL node types has the exhaustive per-type field tables.

Extension APIs

Four seams extend the platform without modifying it:

Seam	Mechanism
New action adapters	Implement the async `Adapter` trait in a new crate and register it, and then `action` nodes target it by name. Its `descriptor()` generates the reference page. Adapters
New AI providers	Implement the cloud-provider trait, add response-parsing tests, and register it. The unified `ai` node picks it via `provider`.
New node types	Author a JSON catalog entry that holds the schema, defaults, command tree, and lowering. No per-type code is needed. Flows and nodes
New service integrations	Add a `service` catalog entry with a `serviceIntegration` descriptor that holds the base URL, auth scheme, and operations.

Shared TypeScript contracts

The @flow/shared-types workspace package mirrors the Rust domain types, including FlowNode, the graph wire shapes, catalog entry DTOs, and execution events. This means any TypeScript host consumes the same contracts the desktop uses. Rust remains the source of truth, and the DTO layer and TypeScript mirror are kept in lockstep.

The DSL as an interface

The .flow text format is itself a stable programmatic surface. It is parseable and serializable, it is a canonical-form fixed point, and it is validated before execution. Grammar reference.