Skip to content

Workflows API ​

Workflows are DAGs of lens nodes connected by edges. Community Edition documents them through repository-backed interfaces, workflow RPCs, workflow event types, and the execution engine reference.

Primary database surfaces ​

  • lenses.workflows
  • lenses.workflow_nodes
  • lenses.workflow_edges
  • lenses.workflow_runs
  • lenses.workflow_node_results
  • lenses.workflow_run_events
  • vw_workflows

Canonical types ​

From workflowsRepository.ts:

  • WorkflowRecord
  • WorkflowNodeRecord
  • WorkflowEdgeRecord
  • CreateWorkflowInput
  • UpdateWorkflowInput
  • UpsertNodeInput
  • UpsertEdgeInput
  • WorkflowVersionRecord
  • WorkflowRunRecord
  • WorkflowNodeResultRecord
  • WorkflowRunEventRecord
  • WorkflowsListFilter

From workflow-events.types.ts:

  • WorkflowSseEventEnvelope
  • WorkflowEventType
  • WorkflowRunStatus
  • WorkflowNodeStatus

Supported flows ​

Community Edition currently supports:

  • my workflows listing
  • popular workflows listing
  • template workflows
  • workflow detail
  • workflow bootstrap for builder load
  • create, update, fork
  • node and edge upsert/delete
  • run start
  • run detail and node results
  • run event append/list
  • workflow version list/create/publish/restore

Existing workflow RPCs ​

RPCPurpose
fn_get_my_workflowsowner listing with filters
fn_workflows_get_popularpublic popular workflows
fn_list_template_workflowspublic template strip
fn_workflow_get_detailworkflow detail record
fn_workflow_get_bootstrapworkflow + nodes + edges
fn_workflow_get_nodesnodes only
fn_workflow_get_edgesedges only
fn_workflow_createcreate workflow
fn_update_workflowupdate workflow metadata
fn_clone_workflowfork workflow
fn_upsert_workflow_nodesinsert/update nodes
fn_upsert_workflow_edgesinsert/update edges
fn_delete_workflow_nodedelete node
fn_delete_workflow_edgedelete edge
fn_start_workflow_runcreate or reuse run
fn_workflow_get_runrun record
fn_workflow_get_node_resultsnode result list
fn_update_workflow_node_resultnode result status/output
fn_update_workflow_run_statusrun status
fn_append_workflow_run_eventappend event for timeline/SSE replay
fn_list_workflow_run_eventsevent replay
fn_tag_workflow_runowner/service tagging
fn_workflow_get_versionsversion list
fn_workflow_create_versioncreate version snapshot
fn_publish_workflow_versionpublish version
fn_restore_workflow_versionrestore version

Typical list filter ​

WorkflowsListFilter currently supports:

ts
type WorkflowsListFilter = {
  visibility?: 'public' | 'private' | 'unlisted'
  sort?: 'updated_at' | 'created_at' | 'battle_count'
  search?: string
}

Example read flows ​

My workflows ​

ts
await workflowsService.listByLenserPaginated(lenserId, 0, 20, {
  visibility: 'private',
  sort: 'updated_at',
  search: 'research',
})
ts
await workflowsService.getPopular(0, 12, 'summary')

Builder bootstrap ​

ts
await workflowsService.getBootstrap(workflowId)

Starting a run ​

Workflow runs are started through fn_start_workflow_run.

The client-side useWorkflowRun hook derives an idempotency key from workflowId and canonicalized root inputs so duplicate submissions reuse the same run where supported.

Who triggers a run vs. who executes it ​

These are two independent axes on lenses.workflow_runs.

trigger_mode records what caused the run:

ValueCause
manuala person started it (web builder, CLI)
schedulea cron schedule or an event trigger
apia headless caller: MCP tool or inbound webhook
subflowa parent workflow or agent team run

executor records what runs it, and is the only field any claimer inspects:

ValueRuns onDurability
worker (default)the background workersurvives a closed browser tab; recovered by the stale-run loop if a worker dies
clientthe browser tab that started itmust heartbeat via fn_heartbeat_client_workflow_run; retired by the reaper if the tab goes away

client is reserved for runs whose credentials the server cannot reach — BYOK funding sources, where the API key is held in the browser. Everything else defaults to worker, so a run does not depend on a tab staying open.

Pass p_executor to choose explicitly. Runs are refused while the system kill switch is active.

Durability guarantees ​

  • A worker run left non-terminal with a stale heartbeat is adopted by the recovery loop and resumed, skipping nodes that already completed.
  • A client run whose tab stops heartbeating is failed by fn_reap_abandoned_workflow_runs, along with its non-terminal node results, with the reason recorded in metadata.reaped_reason.
  • Reopening /workflows/:id/run/:runId reattaches to an in-flight run.

Explicit beta limitations ​

  • Browser execution only supports a limited provider set. See useWorkflowExecution.ts.
  • Cloud BYOK workflow execution is platform-executor dependent and not a self-host guarantee.
  • SSE/event replay is best-effort and reconnect-aware, but the docs must not claim it is fully production-hardened yet.
  • Workflow versioning exists, but the overall workflow product is still incomplete.
  • Recovery, stale-run claiming, and scale hardening are in progress through the 2026 workflow migrations.

Auth and access ​

OperationAuth
public detail/template/popular readsanon where the workflow is public
personal workflowsowner-only
create/update/forkauthenticated, usually owner-scoped
run mutation and event appendauthenticated or service-backed depending on call site