flujo-ai 3.40.0 → 3.41.0

package/.next/static/chunks/app/docs/page-c466a58caf5e3336.js

@@ -1 +0,0 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[9040],{20938:(e,t,s)=>{Promise.resolve().then(s.bind(s,71113))},53228:(e,t,s)=>{"use strict";s.d(t,{G:()=>a});let a={LOG_LEVEL:3,INCLUDE_TOOL_CALLS_IN_RESPONSE:!0,ENABLE_EXECUTION_TRACKER:!1,ENABLE_REVERT_TO_HERE:!1}},71113:(e,t,s)=>{"use strict";s.r(t),s.d(t,{default:()=>T});var a=s(95155),o=s(94049),n=s(12115),r=s(28548),i=s(2300),l=s(25635),d=s(97322),p=s(9562),c=s(56422),u=s(21067),m=s(32683),h=s(51611),f=s(43634);let y=[{id:"openai",name:"Chat — OpenAI-compatible",description:'A drop-in OpenAI-compatible surface. In OpenAI-compatible clients (Roo Code, Cline, Cursor, the OpenAI SDK, …) set the Base URL to this instance + "/v1" (e.g. http://localhost:4200/v1) and the model to a flow id (format flow-<NAME>, as listed by /v1/models).',endpoints:[{method:"POST",alsoMethods:["GET","OPTIONS"],path:"/v1/chat/completions",summary:"OpenAI-compatible chat completion. Runs a FLUJO flow as the model. Supports streaming and non-streaming. CORS-enabled; rate-limited (~6000 req/min).",paramsLabel:"Body",params:[{name:"model",type:"string",required:!0,description:"Flow to run, as flow-<NAME>."},{name:"messages",type:"ChatMessage[]",required:!0,description:"Conversation messages (OpenAI shape)."},{name:"stream",type:"boolean",description:"Stream the response as SSE chunks."},{name:"flujo",type:"boolean",description:"Enable FLUJO-specific behavior."},{name:"conversation_id",type:"string",description:"Reuse/continue an existing conversation."},{name:"requireApproval",type:"boolean",description:"Pause for manual tool-call approval."},{name:"flujodebug",type:"boolean",description:"Run in the visual debugger (single-step)."}],response:"OpenAI ChatCompletion object, or an SSE stream of chunks when stream=true."},{method:"GET",path:"/v1/models",summary:"List all flows as OpenAI-style models.",response:'{ object: "list", data: [{ id: "flow-<NAME>", object: "model" }, ...] }'}]},{id:"conversations",name:"Conversations & Execution",description:"Manage conversations and drive flow execution: live event streaming (SSE), tool-call approval, cancellation, and visual-debugger stepping.",endpoints:[{method:"GET",path:"/v1/chat/conversations",summary:"List all conversations (id, title, flowId, createdAt, updatedAt, status), newest first.",response:"Conversation summary array."},{method:"POST",path:"/v1/chat/conversations",summary:"Create a new conversation and initialize its execution state.",paramsLabel:"Body",params:[{name:"id",type:"string",required:!0,description:"Client-generated conversation id."},{name:"title",type:"string",required:!0,description:"Display title."},{name:"flowId",type:"string",required:!0,description:"Flow bound to this conversation."},{name:"createdAt",type:"number",required:!0,description:"Unix ms timestamp."},{name:"updatedAt",type:"number",required:!0,description:"Unix ms timestamp."}]},{method:"GET",alsoMethods:["PATCH","DELETE"],path:"/v1/chat/conversations/{conversationId}",summary:"GET the displayed conversation (messages + metadata); PATCH updates flowId; DELETE removes the conversation and its event log.",paramsLabel:"Body",params:[{name:"flowId",type:"string",description:"New flow id (PATCH only)."}],response:"Conversation with messages, plus usage (token totals, per-node breakdown), status, and contextInfo (latest prompt-token count + the bound model's context window — what the chat token counter and context meter display).",notes:["Messages are a projection of the append-only conversation log when one exists (legacy conversations without a log are served as stored). Node system prompts are never included.","Subflow steps appear inline as depth-tagged, display-only messages (nested in the chat UI); they are never part of the parent's model context."]},{method:"GET",path:"/v1/chat/conversations/{conversationId}/events",summary:"Server-Sent Events stream of execution events (node:enter/exit, message, usage, run:*). Supports Last-Event-ID reconnect.",paramsLabel:"Query",params:[{name:"fromSeq",type:"number",description:"Replay events from this sequence number."}],response:"text/event-stream of ExecutionEvent objects with monotonic seq ids."},{method:"POST",path:"/v1/chat/conversations/{conversationId}/respond",summary:"Approve or reject a pending tool call; resumes execution when all pending calls are handled.",paramsLabel:"Body",params:[{name:"action",type:'"approve" | "reject"',required:!0,description:"Decision for the tool call."},{name:"toolCallId",type:"string",required:!0,description:"Which pending tool call."}]},{method:"POST",path:"/v1/chat/conversations/{conversationId}/cancel",summary:"Request cancellation of an in-progress run (sets the isCancelled flag)."},{method:"PUT",path:"/v1/chat/conversations/{conversationId}/breakpoints",summary:"Set the visual-debugger breakpoint node ids.",paramsLabel:"Body",params:[{name:"breakpoints",type:"string[]",required:!0,description:"Node ids to break on."}]},{method:"POST",path:"/v1/chat/conversations/{conversationId}/debug/step",summary:"Execute exactly one productive step (only when status is paused_debug); pauses after advancing."},{method:"POST",path:"/v1/chat/conversations/{conversationId}/debug/continue",summary:"Resume a debug session — run freely to the next pause, tool approval, or completion."},{method:"PATCH",path:"/v1/chat/conversations/{conversationId}/edit-state",summary:"Edit paused debug state (a message's content, or the next node to run). Only when paused_debug.",paramsLabel:"Body",params:[{name:"messageId",type:"string",description:"Message to edit."},{name:"content",type:"string",description:"New message content."},{name:"currentNodeId",type:"string",description:"Override the next node."}]}]},{id:"model",name:"Models",description:"CRUD for model configurations and provider model discovery. API keys are encrypted at rest and never returned to the browser in clear text.",endpoints:[{method:"GET",alsoMethods:["POST"],path:"/api/model",summary:"GET lists all models; POST creates a model (409 on duplicate name, 201 on success).",paramsLabel:"Body",params:[{name:"model",type:"Model",required:!0,description:"Model config (POST). Secrets are stored encrypted."}],notes:["Stored API keys are masked before reaching the frontend — never expect a clear-text key in a response."]},{method:"GET",alsoMethods:["PUT","DELETE"],path:"/api/model/{id}",summary:"GET / PUT / DELETE a single model. The path id is authoritative on PUT. DELETE returns 204."},{method:"POST",path:"/api/model/provider",summary:"Fetch available models from a provider, using a supplied or stored API key (resolved server-side).",paramsLabel:"Body",params:[{name:"baseUrl",type:"string",required:!0,description:"Provider base URL."},{name:"modelId",type:"string",description:"Existing model whose stored key to reuse."},{name:"searchTerm",type:"string",description:"Filter the returned model list."}],notes:["Accepts an apiKey only inbound to query the provider; keys are never echoed back to the client."]}]},{id:"flow",name:"Flows",description:"CRUD for flow definitions, programmatic flow authoring (FlowSpec), LLM flow generation, and prompt rendering for individual nodes. For creating flows programmatically, prefer POST /api/flow/compile with a FlowSpec — the raw Flow format (ReactFlow JSON) is the internal canvas representation and easy to get subtly wrong.",endpoints:[{method:"POST",path:"/api/flow/compile",summary:"Compile a FlowSpec (the semantic authoring format — see below) into a complete flow, validate it, and optionally save it. Deterministic, no LLM: layout, ids, handles, and MCP wiring are generated for you. THE recommended way for external apps and agents to create flows. Also exposed as MCP tools (create_flow / validate_flow_spec) on /mcp-flows.",paramsLabel:"Body",params:[{name:"spec",type:"FlowSpec",required:!0,description:"The flow specification (format below)."},{name:"save",type:"boolean",description:"Persist the flow — only happens when validation finds ZERO errors."}],response:"{ flow, validation: { issues, errorCount, warningCount, isRunnable }, saved } — 201 when saved, 200 otherwise. Iterate on the issues until clean.",details:'A FlowSpec is a JSON object describing a FLUJO flow semantically — node keys and edges, no coordinates, no ids, no layout:\n{\n  "name": "short_flow_name",            // letters/digits/_/- only\n  "description": "what the flow does",\n  "nodes": [ ... ],\n  "edges": [ ... ]\n}\n\nNODE TYPES:\n- { "key": "unique_key", "type": "start", "label": "...", "prompt": "system-level instructions for the whole flow" }\n- { "key": "...", "type": "process", "label": "...", "description": "what this step does",\n    "model": "<model id or name from the catalog>",\n    "prompt": "instructions for this step",\n    "servers": [ { "name": "<server name>", "tools": ["tool_a"] } ],   // optional; omit "tools" to enable all\n    "inputMode": "full-history" | "latest-message" | "isolated",       // optional, default full-history. Reshapes ONLY the wire view the model sees (persisted history stays lossless): full-history = the whole assembled context; latest-message = leading system prompt(s) + the most recent EXCHANGE (the last user message + the last assistant response, intermediate turns since the last user message dropped) + this turn\'s in-flight tool calls/results; isolated = system prompt(s) + isolatedPrompt as a synthetic user message, prior conversation dropped. NOTE: for Claude-subscription models the whole wire history (incl. prior tool calls/results under full-history) is flattened into one text prompt rather than sent as native tool turns\n    "isolatedPrompt": "...",                                            // only with inputMode "isolated"\n    "allowCallerPrompt": true | false,                                 // optional, only with inputMode "isolated"; default true — a step that hands off to this isolated step may pass a "prompt" via its handoff tool that overrides "isolatedPrompt". Set false to forbid it\n    "outputMode": "full-conversation" | "latest-message",              // optional, default full-conversation; latest-message hides this step\'s tool calls/results from later steps (they see only its final response)\n    "maxTurns": 20,                                                     // optional; per-step cap on agentic tool-loop turns (retry-until-done in ONE node). Unset = model/system default (50)\n    "allowedTools": ["tool_a"],                                        // optional; step-level tool allowlist (independent of servers[].tools)\n    "captureVariable": "NAME",                                         // optional; save this step\'s output into a run variable other steps inject with ${var:NAME}\n    "captureKv": "NAME",                                               // optional; ALSO save this step\'s output to a PERSISTENT cross-run key other steps inject with ${kv:NAME} (see rule 9d)\n    "excludeModelPrompt": true|false,                                   // optional; drop the model\'s base prompt\n    "excludeStartNodePrompt": true|false,                              // optional; drop the start node\'s prompt for this step\n    "excludeSystemPrompt": true|false }                                // optional; drop the workflow/handoff guidance block\n- { "key": "...", "type": "subflow", "label": "...",\n    "flow": "<existing flow name or id>",          // reference an EXISTING flow, OR:\n    "subflowSpec": { ...a nested FlowSpec... },     // define a brand-new child flow INLINE (compiled into its own flow and wired automatically), OR fan out concurrently:\n    "parallelFlows": ["flow_a", "flow_b"],          // run several EXISTING child flows CONCURRENTLY, same input to each, outputs joined; OR:\n    "parallelSubflowSpecs": [ { ...FlowSpec... } ], // run several INLINE child flows concurrently; OR:\n    "parallelFlowsVariable": "NAME",                // DYNAMIC fan-out (rule 7b): pick the target flows AT RUNTIME from run variable ${var:NAME} (a JSON array of flow ids/names, or newline list); mutually exclusive with mapOverList\n    "mapOverList": true | false,                    // optional; run the SINGLE child ("flow"/"subflowSpec") ONCE PER ITEM parsed from the input; mutually exclusive with parallelFlows/parallelSubflowSpecs\n    "itemSplit": "json-array" | "lines",            // optional (mapOverList only), how to split the input into items, default json-array\n    "sequential": true | false,                     // optional (mapOverList only), run items one at a time in order instead of concurrently, default false\n    "spawnBriefs": ["brief 1", "brief 2"],          // optional (rule 7d); run the SINGLE child once PER BRIEF, in parallel — the author-defined spawn set; mutually exclusive with parallelFlows/parallelSubflowSpecs/mapOverList\n    "concurrencyLimit": 4,                          // optional (parallel / mapOverList / spawn), default 4\n    "joinSeparator": "\\n\\n---\\n\\n",              // optional (parallel / mapOverList / spawn), string between joined lane outputs, default "\\n\\n"\n    "errorStrategy": "collect-all" | "fail-fast",   // optional (parallel / mapOverList / spawn), default collect-all\n    "inputMode": "full-history" | "latest-message" | "isolated",   // optional, default full-history. DIFFERS from a process node: history modes ALWAYS sanitize the parent transcript first — system messages, tool-result messages, and ANY assistant turn that made tool calls are dropped (only user + prose-only assistant messages survive). full-history = the full sanitized transcript; latest-message = the most recent EXCHANGE of the sanitized transcript (the last user message + the last assistant response after it, intermediate turns dropped); isolated = ignore the parent conversation and send "prompt" as the child\'s single user message\n    "allowCallerPrompt": true | false,             // optional, only with inputMode "isolated"; default true — a routing step may pass a "prompt" via its handoff tool that overrides the subflow\'s "prompt". Set false to forbid it\n    "allowCallerFanout": true | false,             // optional (subflow); makes this a SPAWNABLE sub-agent: the routing step may call its handoff tool SEVERAL TIMES in one turn, each call with a "task" brief spawning one parallel instance of the child flow (rule 7c)\n    "captureVariable": "NAME",                     // optional; save the subflow\'s output into a run variable other steps inject with ${var:NAME}\n    "captureResource": "NAME",                     // optional; ALSO save the subflow\'s output as a tracked run resource (${res:NAME}, rule 9b)\n    "captureKv": "NAME",                           // optional; ALSO save the subflow\'s output to a PERSISTENT cross-run key (${kv:NAME}, rule 9d)\n    "outputMode": "steps" | "final-only" }\n- { "key": "...", "type": "finish" }                              // a finish node is ALWAYS named "Finish Node"; omit "label" (any label you supply is ignored)\n- { "key": "...", "type": "signal", "label": "...",                // fire-and-forget event (rule 11): emits {topic, payload} then passes through unchanged\n    "topic": "<event topic other flows\' triggers listen for>",     // REQUIRED — a signal with no topic emits nothing\n    "payloadTemplate": "event body, may use ${var:NAME}" }         // optional; defaults to the node prompt\n- { "key": "...", "type": "resource", "label": "...",              // OPTIONAL/advanced (rule 9c): a data artifact shown in the graph\n    "server": "<server name>", "uri": "<resource uri>",            // EITHER a static MCP resource…\n    "runName": "NAME" }                                            // …OR a run artifact steps produce/consume\n\nEDGES: { "from": "<node key>", "to": "<node key>", "bidirectional": true|false,\n         "condition": { "kind": "contains"|"regex"|"equals", "value": "...",\n                        "target": "last-assistant"|"last-message",  // optional, default last-assistant\n                        "ignoreCase": true|false, "negate": true|false } }   // condition optional; process-node edges only\n\nRULES:\n1. Exactly ONE start node; at least one finish node reachable from it.\n2. Every process node MUST reference a configured model (by id, display name, or name).\n3. A process step uses MCP tools ONLY via its "servers" list — never emit nodes of type "mcp".\n4. Do not embed ${tool:...} or ${resource:...} references in prompts — tools are wired through "servers".\n5. Branching: give a process node multiple outgoing edges; its model decides where to hand off at runtime. "bidirectional": true lets the target hand back to the source (agent <-> agent).\n5b. Deterministic routing: give a process node\'s outgoing edges a "condition" to route WITHOUT the model — the engine takes the first outgoing edge whose predicate matches the last message (default the step\'s own last assistant message), and a bare (condition-less) edge is the fallback. Use this for reliable data-driven branches (e.g. output contains "FAIL" -> fix step, else -> publish) instead of relying on a small model to emit a handoff. Only process-node edges may carry a condition. Without any condition on a node, that node keeps model-decided handoff (rule 5). If the model still calls a handoff tool, that wins over the condition.\n6. A subflow node may have only ONE outgoing edge. Give it EITHER a "flow" (naming an existing flow) OR a "subflowSpec" (an inline nested FlowSpec that becomes its own child flow) — not both. A "subflowSpec" may itself contain subflow nodes with their own "subflowSpec" (bounded nesting), so you can author whole multi-level flows in one object.\n7. A subflow node may instead fan out to SEVERAL child flows CONCURRENTLY via "parallelFlows" (existing flows) or "parallelSubflowSpecs" (inline). These are STATIC (fixed at author time): the same input is sent to every lane and their outputs are joined. This is about multiple CHILDREN, not successors — the single-outgoing-edge rule (rule 6) still holds. Prefer "parallelFlows" for large fan-outs.\n7b. For DYNAMIC fan-out — when the set of target flows should be decided AT RUNTIME by an earlier step — use "parallelFlowsVariable": "NAME". An upstream process/subflow node captures a JSON array of flow ids/names (or a newline list) into run variable NAME via "captureVariable": "NAME"; this subflow node then fans out over exactly those flows. Unknown ids and a self-reference are dropped, the count is capped, and a non-empty resolution overrides any static "parallelFlows" (empty falls back to it). Mutually exclusive with "mapOverList". Still one outgoing edge (rule 6).\n7c. For AGENTIC spawning — when the ROUTING MODEL itself should split the work at the very moment it hands off — set "allowCallerFanout": true on the target subflow node. This makes it a SPAWNABLE sub-agent: its handoff tool gains an optional "task" (string) argument and the routing model may call the tool SEVERAL TIMES IN ONE TURN, each call spawning one parallel instance of the child flow briefed with that call\'s "task". All instances run concurrently, their outputs are joined in call order, and the flow continues once every instance finishes. A call with no "task" is a plain single handoff. Caller briefs override "spawnBriefs"/"parallelFlows"/"parallelFlowsVariable"; the count is capped. Mutually exclusive with "mapOverList". Still one outgoing edge (rule 6). Use 7c when the deciding (routing) step should choose how to split the work; use 7d\'s "spawnBriefs" when the AUTHOR fixes the briefs; use 7b when an earlier step computes a set of DIFFERENT flows.\n7d. For AUTHOR-DEFINED spawning — a fixed set of parallel briefs for ONE sub-agent — give the subflow node "spawnBriefs": ["...", "..."]. Every visit runs the single child once per brief, concurrently (same pool/tuning as parallel). Each brief may inject ${var:NAME}/${res:NAME}/${kv:NAME}. With inputMode "isolated" the brief is the lane\'s whole prompt; with history modes each lane sees the conversation plus its brief as the closing instruction. Mutually exclusive with "parallelFlows"/"parallelSubflowSpecs"/"mapOverList"; needs a single child ("flow"/"subflowSpec").\n8. A subflow node may instead run its SINGLE child flow ONCE PER ITEM via "mapOverList": true. The input is split into items by "itemSplit" ("json-array" default, or "lines"), each item is sent to its own child run, and the per-item outputs are joined (same pool/tuning as parallel). Use "sequential": true to run items in order. Mutually exclusive with "parallelFlows"/"parallelSubflowSpecs".\n9. Named variables (scratchpad): a step can save its output with "captureVariable": "NAME" (process or subflow) and any LATER step injects it with ${var:NAME} inside its "prompt" / "isolatedPrompt" / subflow prompt. This survives "latest-message"/"isolated" scoping, unlike conversation history — use it to carry a todo list, a file path, a diff, or a captured result across steps that don\'t share history. ${var:NAME} is run-scoped and plaintext; it is DISTINCT from ${global:VAR} (configured secrets/config, resolved only for tool args). Capture a subflow\'s output on the PARENT subflow node — a variable set inside a child flow is not visible to the parent.\n9b. Run resources (tracked data): a SUBFLOW may use "captureResource": "NAME" because its folded child output is a concrete result. A PROCESS must use an explicit Resource node: process→resource arms write_resource so the process writes the full artifact; resource→process injects it into a reader with ${res:NAME}. Do not put passive captureResource on a process node. Large or binary MCP tool results are auto-captured as run resources without any spec field.\n9c. Resource nodes are OPTIONAL/advanced — most flows should use conversation history. Resource edges are data wiring, not flow control: they never carry conditions and do not count as a step\'s successor.\n9d. Persistent state (cross-run): "captureKv": "NAME" (process or subflow) saves the step\'s output to a PERSISTENT key-value store that SURVIVES ACROSS RUNS, injected by any step with ${kv:NAME}. Unlike ${var:} / ${res:} (discarded when the run ends), ${kv:} is what a long-lived SCHEDULED flow uses to carry a loop counter, a pagination cursor, a last-seen id, or a flag to its NEXT run. By default a key lives on the flow\'s FOLDER board (flows in the same folder share it); prefix the name to change scope: "flow/NAME" (this flow only) or "global/NAME" (whole instance). Plaintext, never secrets (distinct from ${global:VAR}). A model can also read/update a key mid-run via the built-in "flujo" server\'s kv_get / kv_set tools.\n10. Keep flows minimal — only the steps the task needs. Write clear, specific prompts and labels; fill "description" on process nodes.\n11. Signals (fire-and-forget events): a "signal" node is a deterministic pass-through that, when the path reaches it, emits an event {topic, payload} onto the flow-run event bus and then continues to its successor unchanged (it never calls a model or touches the conversation). Use it when the flow should notify or kick off ANOTHER flow mid-run — a flow-event trigger configured elsewhere listens for the same "topic" (e.g. "when the review finds blockers, emit a review-blocked signal"). Always give it a "topic" (a signal with no topic emits nothing); "payloadTemplate" is the optional event body and may inject ${var:NAME}. Make emission conditional by putting a conditioned edge (rule 5b) INTO the signal node.\n12. Input vs output modes are two DISTINCT axes whose value names differ per node type (issue #152 clarification). inputMode ("full-history" | "latest-message" | "isolated") controls what a step RECEIVES and exists on BOTH process and subflow nodes, but they behave differently: a process node keeps the current turn\'s tool calls/results, while a subflow node ALWAYS strips system/tool-result/tool-call turns from the parent transcript in every history mode (see the inputMode notes above). "latest-message" means "from the most recent user message onward", NOT "last user + last assistant". outputMode controls what LATER steps see of a step\'s work and is a SEPARATE enum per node type: a process node uses "full-conversation" | "latest-message" (latest-message hides this step\'s tool exchange from later steps), a subflow node uses "steps" | "final-only" (live-view folding only). Common word traps: "last-message" = inputMode latest-message; "full-conversation" is a process outputMode value, NOT an input mode. A subflow\'s final answer is always injected back into the parent transcript regardless of outputMode.'},{method:"POST",path:"/api/flow/generate",summary:"Generate a draft flow from a natural-language description using one of your configured models. The model authors a FlowSpec, FLUJO compiles + validates it and feeds problems back for a bounded number of repair rounds. The generator can always SEARCH the public MCP registry; with allowInstall it can also INSTALL servers it needs. Returns an UNSAVED draft (the UI opens it in the builder for review); persist via the normal save path or /api/flow/compile.",paramsLabel:"Body",params:[{name:"description",type:"string",required:!0,description:"What the flow should do, in plain language."},{name:"modelId",type:"string",required:!0,description:"Configured model that does the generating."},{name:"maxRepairs",type:"number",description:"Repair rounds after the first attempt (default 1, max 2)."},{name:"allowInstall",type:"boolean",description:"Let the generator install MCP servers from the public registry (downloads + RUNS third-party packages on this machine). Off by default."}],response:"{ flow, validation, attempts, installedServers } — the flow is a draft; nothing flow-related is persisted by this endpoint (installed servers ARE persisted).",notes:["allowInstall executes third-party code with this machine's user permissions — opt in deliberately."]},{method:"GET",alsoMethods:["POST"],path:"/api/flow",summary:"GET lists all flow definitions; POST creates a flow (create-only; 409 if the id exists). POST takes the raw internal Flow format — prefer /api/flow/compile for programmatic creation.",paramsLabel:"Body",params:[{name:"flow",type:"Flow",required:!0,description:"Flow object including id (POST)."}]},{method:"GET",alsoMethods:["PUT","DELETE"],path:"/api/flow/{id}",summary:"GET / PUT / DELETE a single flow. On PUT the path id wins over the body id (404 if missing)."},{method:"POST",path:"/api/flow/prompt-renderer",summary:"Render the assembled prompt for a node within a flow.",paramsLabel:"Body",params:[{name:"flowId",type:"string",required:!0,description:"Flow containing the node."},{name:"nodeId",type:"string",required:!0,description:"Node to render."},{name:"options",type:"object",description:"Render options."}]}]},{id:"planned-executions",name:"Automation — Triggers",description:"Run flows headlessly on triggers: schedules (cron), inbound webhooks, and more. Managed from Automation > Triggers; each run is recorded in a per-trigger run history. The compatibility API remains /api/planned-executions.",endpoints:[{method:"GET",alsoMethods:["POST","PATCH"],path:"/api/planned-executions",summary:"GET lists all planned executions with live trigger status and last run; POST creates one; PATCH toggles the global pause switch ({ paused: boolean }).",response:"GET: { paused, executions: [{ execution, status, lastRun }] }."},{method:"GET",alsoMethods:["PATCH","DELETE"],path:"/api/planned-executions/{id}",summary:"GET / PATCH / DELETE a single planned execution. PATCH takes a partial config and re-arms the trigger."},{method:"POST",path:"/api/planned-executions/{id}/run",summary:"Run now: fire the execution immediately (even while disabled or paused) and wait for the run.",response:"{ record: RunRecord } with status, output preview, and token usage."},{method:"GET",path:"/api/planned-executions/{id}/runs",summary:"The execution’s run history (newest 100 runs, oldest first)."},{method:"POST",path:"/api/planned-executions/preview-schedule",summary:"Validate a cron pattern and preview its next fire times (editor helper).",paramsLabel:"Body",params:[{name:"cron",type:"string",required:!0,description:"Cron pattern (5 or 6 fields)."},{name:"timezone",type:"string",description:"IANA timezone name."}],response:"{ valid, error?, nextRuns: string[] }."},{method:"POST",path:"/api/webhooks/{id}",summary:"Inbound webhook trigger. Fires the planned execution with the request body as trigger context and responds 202 { runId } immediately (the flow runs in the background). For a synchronous answer use /v1/chat/completions instead.",paramsLabel:"Query",params:[{name:"token",type:"string",required:!0,description:"Per-execution secret (alternatively send the X-Flujo-Token header)."}],notes:["Localhost-only by default; external callers must be explicitly allowed per execution.","The webhook body is untrusted input to the flow — prompts should treat it as data."]}]},{id:"mcp",name:"MCP Servers",description:"Manage MCP server configurations, connection state, tool discovery, and tool invocation.",endpoints:[{method:"GET",alsoMethods:["POST"],path:"/api/mcp/servers",summary:"GET lists all MCP server configs; POST registers a new one (409 on duplicate name).",paramsLabel:"Body",params:[{name:"config",type:"MCPServerConfig",required:!0,description:"Server config (POST)."}]},{method:"GET",alsoMethods:["PUT","DELETE"],path:"/api/mcp/servers/{name}",summary:"GET / PUT / DELETE a server config. PUT merges fields; toggling disabled connects/disconnects; a new name triggers a validated rename."},{method:"GET",path:"/api/mcp/servers/{name}/status",summary:"Live connection status. Always 200, even when the server is down.",response:"{ status, ... }"},{method:"GET",path:"/api/mcp/servers/{name}/tools",summary:"List tools exposed by a connected server.",response:"{ tools, error? } (empty tools + error when disconnected)."},{method:"POST",path:"/api/mcp/servers/{name}/tools/{toolName}",summary:"Invoke a tool on a server. Status may reflect the tool itself (408 on timeout).",paramsLabel:"Body",params:[{name:"args",type:"Record<string, unknown>",required:!0,description:"Tool arguments."},{name:"timeout",type:"number",description:"Optional timeout (ms)."}]},{method:"POST",path:"/api/mcp/test-connection",summary:"Run a real MCP handshake against an unsaved config (tests custom CAs and headers) without registering it.",paramsLabel:"Body",params:[{name:"config",type:"MCPServerConfig",required:!0,description:"Config to test."}]},{method:"POST",path:"/api/mcp/cancel",summary:"Cancel an in-progress tool execution; force-reconnects if no token is supplied.",paramsLabel:"Body",params:[{name:"reason",type:"string",required:!0,description:"Cancellation reason."}]}]},{id:"mcp-proxy",name:"FLUJO as an MCP server (proxy)",description:'Re-expose a configured MCP server to EXTERNAL MCP clients (Claude Desktop, Cursor, Cline, mcp-inspector, …) so you configure the server once in FLUJO and reach it everywhere. Enable per server via the "Expose to external apps" toggle on its card. In your MCP client, add a Streamable-HTTP server with the URL below. One downstream server per endpoint, so tool names are unchanged. Localhost-only for now (no auth token in this version — see the security roadmap).',endpoints:[{method:"POST",alsoMethods:["GET","DELETE"],path:"/mcp-proxy/{server}",summary:'A Streamable-HTTP MCP endpoint that forwards tools/list and tools/call to the named downstream MCP server. {server} is the configured server name; it must have "Expose to external apps" enabled (otherwise 404). Rejects non-localhost requests.',response:"MCP JSON-RPC over Streamable HTTP (handled by your MCP client, not called directly)."}]},{id:"mcp-flows",name:"FLUJO as an MCP server (flows + authoring)",description:"A Streamable-HTTP MCP endpoint that exposes FLUJO itself to external MCP clients. Every saved flow is a callable tool (running it ephemerally and returning its output), and three authoring tools let an external agent CREATE flows by sending a semantic FlowSpec — no raw ReactFlow JSON required. Localhost-only (same posture as the proxy).",endpoints:[{method:"POST",alsoMethods:["GET","DELETE"],path:"/mcp-flows",summary:'MCP server with two tool families. Flow tools: one per saved flow (name = slug of the flow name; input = a single "input" string sent as the user turn; runs are ephemeral and never appear in the chat sidebar). Authoring tools: list_flow_building_blocks (models, MCP servers + tools, and existing flows a spec may reference — call first), validate_flow_spec (compile + validate without saving; iterate on the returned issues), create_flow (compile + validate + save; only saves when validation finds zero errors), plus capability acquisition: search_mcp_marketplace (search the public registry) and install_mcp_server (install + connect a registry server — downloads and RUNS third-party packages on the FLUJO host; required keys can be passed via its env argument). The FlowSpec format is documented on POST /api/flow/compile above and inside the tools\' own descriptions.',response:"MCP JSON-RPC over Streamable HTTP (handled by your MCP client, not called directly)."}]},{id:"oauth",name:"OAuth (for MCP)",description:"OAuth authorization flow for MCP servers that require it. Tokens are stored server-side and never sent to the browser.",endpoints:[{method:"POST",path:"/api/oauth/initiate",summary:"Begin the OAuth flow for a server; dynamically registers a client and returns an authorization URL.",paramsLabel:"Body",params:[{name:"serverName",type:"string",required:!0,description:"MCP server to authorize."}]},{method:"GET",alsoMethods:["POST"],path:"/api/oauth/callback",summary:"OAuth redirect target; exchanges the code for tokens, updates the config, and redirects to /mcp.",notes:["Tokens are persisted server-side only."]},{method:"POST",path:"/api/oauth/reset",summary:"Clear a server's OAuth tokens and force re-authentication on the next connection.",paramsLabel:"Body",params:[{name:"serverName",type:"string",required:!0,description:"Server to reset."}]}]},{id:"env",name:"Environment & Secrets",description:"Global environment variables and server-side encryption operations. Secret values are encrypted at rest and masked as ******** in responses.",endpoints:[{method:"GET",alsoMethods:["POST"],path:"/api/env",summary:"GET reads env vars (secrets masked); POST sets/deletes vars (secrets encrypted server-side).",paramsLabel:"Body",params:[{name:"action",type:'"set" | "setAll" | "delete"',required:!0,description:"Operation."},{name:"key",type:"string",description:"Variable name (set/delete)."},{name:"value",type:"string",description:"Value; the placeholder ******** is ignored."},{name:"metadata",type:"{ isSecret: boolean }",description:"Marks a value for encryption."}],notes:["GET masks secret values unless an internal includeSecrets flag is set; the browser never receives clear-text secrets."]},{method:"POST",path:"/api/encryption/secure",summary:"Server-side encryption operations: initialize, authenticate, change_password, encrypt, verify_password, check_initialized, and status queries.",paramsLabel:"Body",params:[{name:"action",type:"string",required:!0,description:"One of the encryption actions."}],notes:["Passwords and tokens are handled here and stay server-side — never log or surface them in the UI."]}]},{id:"storage",name:"Storage & Backup",description:"Generic key-value storage plus zip backup/restore of selected data.",endpoints:[{method:"GET",alsoMethods:["POST","DELETE"],path:"/api/storage",summary:"GET loads an item by StorageKey (with optional default); POST saves; DELETE clears.",paramsLabel:"Query",params:[{name:"key",type:"StorageKey",required:!0,description:"Storage key."},{name:"defaultValue",type:"JSON",description:"Returned when the key is missing (GET)."}]},{method:"POST",path:"/api/backup",summary:"Create a zip backup of selected items and download it.",paramsLabel:"Body",params:[{name:"selections",type:"string[]",required:!0,description:"e.g. models, mcpServers, flows, chatHistory, settings."}],notes:["A backup may include the encryption key and secrets — handle the downloaded file carefully."]},{method:"POST",path:"/api/restore",summary:"Restore data from a backup zip.",paramsLabel:"Form data",params:[{name:"file",type:"File (zip)",required:!0,description:"Backup archive."},{name:"selections",type:"JSON string[]",required:!0,description:"Which items to restore."}]}]},{id:"system",name:"System & Updates",description:"App initialization, working-directory info, repository operations, and self-update.",endpoints:[{method:"GET",path:"/api/init",summary:"Server-side initialization: verify storage and start enabled MCP servers."},{method:"GET",path:"/api/cwd",summary:"Return the current working directory and the mcp-servers directory path."},{method:"GET",path:"/api/browse",summary:"List a directory of the machine running FLUJO, for the folder-picker dialogs (file-watch triggers, MCP server paths). Defaults to the home directory; includes available drives on Windows.",paramsLabel:"Query",params:[{name:"path",type:"string",description:"Absolute directory path to list."}],response:"{ path, parent, home, sep, drives, entries: [{ name, path, isDirectory }] }",notes:["Exposes backend filesystem listings — like the rest of the API it assumes a single trusted user."]},{method:"POST",path:"/api/git",summary:"Repository operations for MCP servers: clone, install, build, run, exists, readFile, listDir, list, checkUpdates, checkUpdatesBatch, pullUpdates.",paramsLabel:"Body",params:[{name:"action",type:"string",required:!0,description:"Operation to perform."}]},{method:"GET",alsoMethods:["POST"],path:"/api/update",summary:'GET checks for a newer version (git fetch + behind count); POST { action: "apply" } pulls, rebuilds, and restarts.',response:"{ success, isGitRepo, updateAvailable, behindBy?, branch?, currentVersion }"}]}];var g=s(79508);let w={GET:"#2e7d32",POST:"#1565c0",PUT:"#ed6c02",PATCH:"#9c27b0",DELETE:"#c62828",OPTIONS:"#616161"};function v(e){let{method:t}=e;return(0,a.jsx)(r.A,{label:t,size:"small",sx:{bgcolor:w[t],color:"#fff",fontWeight:700,fontFamily:"var(--font-geist-mono), monospace",fontSize:"0.7rem",height:22}})}function b(e){var t,s,n,r;let{endpoint:d}=e;return(0,a.jsxs)(i.A,{variant:"outlined",sx:{p:2,mb:1.5},children:[(0,a.jsxs)(o.default,{sx:{display:"flex",alignItems:"center",gap:1,flexWrap:"wrap",mb:1},children:[(0,a.jsx)(v,{method:d.method}),null==(t=d.alsoMethods)?void 0:t.map(e=>(0,a.jsx)(v,{method:e},e)),(0,a.jsx)(l.A,{component:"code",sx:{fontFamily:"var(--font-geist-mono), monospace",fontSize:"0.9rem",wordBreak:"break-all"},children:d.path})]}),(0,a.jsx)(l.A,{variant:"body2",color:"text.secondary",sx:{mb:1.5*(null!=(s=d.params)&&!!s.length)},children:d.summary}),d.params&&d.params.length>0&&(0,a.jsxs)(o.default,{sx:{mb:1},children:[(0,a.jsx)(l.A,{variant:"caption",sx:{fontWeight:700,textTransform:"uppercase",color:"text.secondary"},children:null!=(r=d.paramsLabel)?r:"Parameters"}),(0,a.jsx)(o.default,{component:"ul",sx:{m:0,mt:.5,pl:2.5},children:d.params.map(e=>(0,a.jsx)(o.default,{component:"li",sx:{mb:.25},children:(0,a.jsxs)(l.A,{variant:"body2",component:"span",children:[(0,a.jsx)(o.default,{component:"code",sx:{fontFamily:"var(--font-geist-mono), monospace",fontWeight:600},children:e.name}),(0,a.jsxs)(o.default,{component:"span",sx:{color:"text.secondary"},children:[" ",e.type,e.required?" \xb7 required":""," — ",e.description]})]})},e.name))})]}),d.response&&(0,a.jsxs)(l.A,{variant:"body2",sx:{mt:.5},children:[(0,a.jsxs)(o.default,{component:"span",sx:{fontWeight:600},children:["Response:"," "]}),(0,a.jsx)(o.default,{component:"span",sx:{color:"text.secondary"},children:d.response})]}),null==(n=d.notes)?void 0:n.map((e,t)=>(0,a.jsxs)(l.A,{variant:"caption",sx:{display:"block",mt:1,color:"warning.main"},children:["⚠ ",e]},t)),d.details&&(0,a.jsx)(o.default,{component:"pre",sx:{mt:1.5,p:1.5,bgcolor:"action.hover",borderRadius:1,fontSize:"0.75rem",fontFamily:"monospace",whiteSpace:"pre-wrap",overflowX:"auto",m:0,mb:0},children:d.details})]})}function E(){let[e,t]=(0,n.useState)(""),[s,r]=(0,n.useState)("");n.useEffect(()=>{r(window.location.origin)},[]);let w=(0,n.useMemo)(()=>{let t=e.trim().toLowerCase();return t?y.map(e=>{let s=e.endpoints.filter(s=>{var a;return"".concat(s.method," ").concat((null!=(a=s.alsoMethods)?a:[]).join(" ")," ").concat(s.path," ").concat(s.summary).toLowerCase().includes(t)||e.name.toLowerCase().includes(t)});return{...e,endpoints:s}}).filter(e=>e.endpoints.length>0):y},[e]);return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(g.default,{eyebrow:"Reference",title:"API documentation",description:"Use FLUJO as an OpenAI-compatible runtime or automate every core resource directly.",icon:f.A,maxWidth:960}),(0,a.jsxs)(d.A,{maxWidth:"md",sx:{py:{xs:3,md:5}},children:[(0,a.jsxs)(i.A,{variant:"outlined",sx:{p:2,mb:3},children:[(0,a.jsx)(l.A,{variant:"subtitle2",gutterBottom:!0,children:"Base URL"}),(0,a.jsx)(o.default,{component:"code",sx:{fontFamily:"var(--font-geist-mono), monospace",fontSize:"0.9rem"},children:s||"http://localhost:4200"}),(0,a.jsxs)(l.A,{variant:"body2",color:"text.secondary",sx:{mt:1},children:["Point any OpenAI SDK at"," ",(0,a.jsx)(o.default,{component:"code",sx:{fontFamily:"var(--font-geist-mono), monospace"},children:(s||"http://localhost:4200")+"/v1"})," ","and set the model to"," ",(0,a.jsx)(o.default,{component:"code",sx:{fontFamily:"var(--font-geist-mono), monospace"},children:"flow-<NAME>"}),". Any API key value is accepted locally."]})]}),(0,a.jsx)(p.A,{fullWidth:!0,size:"small",placeholder:"Search endpoints (path, method, description)…",value:e,onChange:e=>t(e.target.value),sx:{mb:3},InputProps:{startAdornment:(0,a.jsx)(c.A,{position:"start",children:(0,a.jsx)(h.A,{fontSize:"small"})})}}),0===w.length&&(0,a.jsxs)(l.A,{color:"text.secondary",children:["No endpoints match “",e,"”."]}),w.map(e=>(0,a.jsxs)(o.default,{sx:{mb:4},id:e.id,children:[(0,a.jsx)(l.A,{variant:"h6",gutterBottom:!0,children:e.name}),(0,a.jsx)(l.A,{variant:"body2",color:"text.secondary",sx:{mb:2},children:e.description}),e.endpoints.map(e=>(0,a.jsx)(b,{endpoint:e},"".concat(e.method," ").concat(e.path)))]},e.id)),(0,a.jsx)(u.A,{sx:{my:3}}),(0,a.jsxs)(l.A,{variant:"caption",color:"text.secondary",children:["Secrets (API keys, encryption passwords, OAuth tokens) are encrypted at rest and never returned to the browser in clear text. See the project"," ",(0,a.jsx)(m.A,{href:"https://github.com/mario-andreschak/FLUJO",target:"_blank",rel:"noopener",children:"repository"})," ","for source-level details."]})]})]})}let x=(0,s(73288).h)("app/docs/page");function T(){return x.debug("Rendering DocsPage"),(0,a.jsx)(o.default,{component:"div",sx:{minHeight:"100%"},children:(0,a.jsx)(E,{})})}},73288:(e,t,s)=>{"use strict";s.d(t,{h:()=>l});var a=s(53228);let o={VERBOSE:-1,DEBUG:0,INFO:1,WARN:2,ERROR:3},n="number"==typeof a.G.LOG_LEVEL?a.G.LOG_LEVEL:o.ERROR;function r(e){let t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:0;if(t>6)return String(e);if(!(e instanceof Error))return e;let s={name:e.name,message:e.message};for(let a of Object.getOwnPropertyNames(e)){if("name"===a||"message"===a)continue;let o=e[a];"function"!=typeof o&&("stack"===a?s.stack=o:"cause"===a?s.cause=r(o,t+1):"errors"===a&&Array.isArray(o)?s.errors=o.map(e=>r(e,t+1)):s[a]=o)}return s}function i(e,t,s,a,i){if(e>=("number"==typeof i?i:n)){if("function"==typeof a)try{a=a()}catch(e){a="[lazy log data threw]"}let n=new Date().toISOString(),i="[".concat(n,"] [").concat(t,"]"),l="".concat(i," ").concat(s);if(void 0!==a)if(a instanceof Error||"object"==typeof a)try{let e=a instanceof Error?r(a):a,t=JSON.stringify(e,(e,t)=>t instanceof Error?r(t):t,2);l+=":\n".concat(t)}catch(e){l+=": [Object cannot be stringified]"}else l+=": ".concat(a);switch(e){case o.VERBOSE:console.debug("[VERBOSE] ".concat(l));break;case o.DEBUG:console.debug(l);break;case o.INFO:console.info(l);break;case o.WARN:console.warn(l);break;case o.ERROR:console.error(l);break;default:console.log(l)}}}function l(e,t){let s,a=((s=e.replace(/^src\//,"")).startsWith("/")&&(s=s.substring(1)),s);return{verbose:(e,s)=>{i(o.VERBOSE,a,e,s,t)},debug:(e,s)=>{i(o.DEBUG,a,e,s,t)},info:(e,s)=>{i(o.INFO,a,e,s,t)},warn:(e,s)=>{i(o.WARN,a,e,s,t)},error:(e,s)=>{i(o.ERROR,a,e,s,t)}}}},79508:(e,t,s)=>{"use strict";s.d(t,{default:()=>d});var a=s(95155),o=s(33567),n=s(94049),r=s(80777),i=s(25635),l=s(8532);function d(e){let{title:t,description:s,eyebrow:d,icon:p,leading:c,badge:u,actions:m,compact:h=!1,maxWidth:f=1440}=e,y=(0,o.A)();return(0,a.jsx)(n.default,{component:"header",sx:{position:"relative",overflow:"hidden",borderBottom:1,borderColor:"divider",background:"linear-gradient(110deg, ".concat((0,l.X4)(y.palette.primary.main,"dark"===y.palette.mode?.09:.055),", transparent 38%, ").concat((0,l.X4)(y.palette.secondary.main,.045),")"),"&::after":{position:"absolute",top:-90,right:"8%",width:220,height:160,borderRadius:"50%",content:'""',pointerEvents:"none",background:"radial-gradient(circle, ".concat((0,l.X4)(y.palette.primary.main,.16),", transparent 68%)"),filter:"blur(20px)"}},children:(0,a.jsxs)(n.default,{sx:{position:"relative",zIndex:1,display:"flex",width:"100%",maxWidth:f,mx:"auto",px:{xs:2,sm:3,lg:4},py:h?{xs:1.8,sm:2}:{xs:2.2,sm:2.8},alignItems:{xs:"flex-start",md:"center"},justifyContent:"space-between",flexDirection:{xs:"column",md:"row"},gap:2},children:[(0,a.jsxs)(r.A,{direction:"row",spacing:1.5,alignItems:"center",sx:{minWidth:0},children:[c,p&&(0,a.jsx)(n.default,{"aria-hidden":"true",sx:{display:"grid",width:h?40:46,height:h?40:46,flexShrink:0,placeItems:"center",border:"1px solid ".concat((0,l.X4)(y.palette.primary.main,.24)),borderRadius:h?2.8:3.2,color:"primary.light",bgcolor:(0,l.X4)(y.palette.primary.main,.1),boxShadow:"inset 0 1px 0 ".concat((0,l.X4)(y.palette.common.white,.08),", 0 10px 30px ").concat((0,l.X4)(y.palette.primary.main,.12))},children:(0,a.jsx)(p,{sx:{fontSize:h?21:24}})}),(0,a.jsxs)(n.default,{sx:{minWidth:0},children:[(d||u)&&(0,a.jsxs)(r.A,{direction:"row",spacing:1,alignItems:"center",sx:{mb:.35},children:[d&&(0,a.jsx)(i.A,{sx:{color:"primary.light",fontSize:"0.67rem",fontWeight:780,letterSpacing:"0.13em",textTransform:"uppercase"},children:d}),u]}),(0,a.jsx)(i.A,{component:"h1",variant:"h5",sx:{overflow:"hidden",textOverflow:"ellipsis",fontSize:h?"1.2rem":void 0,whiteSpace:{xs:"normal",sm:"nowrap"}},children:t}),s&&(0,a.jsx)(i.A,{variant:"body2",color:"text.secondary",sx:{mt:.45,maxWidth:720,textWrap:"balance"},children:s})]})]}),m&&(0,a.jsx)(n.default,{sx:{display:"flex",width:{xs:"100%",md:"auto"},flexShrink:0,flexWrap:"wrap",alignItems:"center",gap:1,"& > .MuiButton-root":{flex:{xs:"1 1 auto",sm:"0 0 auto"}}},children:m})]})})}}},e=>{e.O(0,[4754,7758,3392,2678,981,5954,9562,8862,8441,1255,7358],()=>e(e.s=20938)),_N_E=e.O()}]);