> ## Documentation Index > Fetch the complete documentation index at: https://flowdrop.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Import workflow from Agent Spec JSON > Convert an Agent Spec flow or document to a FlowDrop workflow. The conversion: - Maps Agent Spec component types to FlowDrop node types - Merges control_flow_connections and data_flow_connections into unified edges - Auto-layouts nodes if no position metadata is present - Preserves Agent Spec component_type in FlowDrop extensions ## OpenAPI ````yaml /api-reference/openapi.yaml post /workflows/import/agentspec openapi: 3.0.3 info: title: FlowDrop™ API description: > FlowDrop is a visual workflow editor for AI applications and data processing pipelines. This API provides comprehensive endpoints for managing workflows, node types, pipeline execution, and port configuration. ## Features - **Workflow Management**: Complete CRUD operations for workflows with nodes and edges - **Node Type Discovery**: Browse and search available node processors with metadata - **Pipeline Execution**: Execute workflows with real-time status tracking and job management - **Port Configuration**: Dynamic port compatibility system with data type management - **Real-time Updates**: Track node execution status and pipeline progress - **Import/Export**: Import and export workflows in JSON format - **Validation**: Workflow validation before execution - **Agent Spec Integration**: Import/export Oracle Open Agent Spec flows and execute on compatible runtimes (WayFlow/PyAgentSpec) ## Architecture - **Frontend**: Svelte 5 + XYFlow for visual workflow editing - **Backend**: Drupal 10/11 with custom node processor plugins - **API**: RESTful JSON API with consistent response format - **Storage**: Drupal entity system with workflow versioning ## Authentication API endpoints require Drupal authentication. Use Bearer token or session-based authentication. ## Rate Limiting - Node Discovery: 100 requests/minute - Workflow Operations: 50 requests/minute - Pipeline Execution: 20 requests/minute ## Error Handling All errors return a consistent format with success flag, error message, and optional details. version: 1.0.0 contact: name: FlowDrop Support email: shibinkidd@gmail.com url: https://www.drupal.org/project/issues/flowdrop?categories=All servers: - url: http://localhost:5173/api/flowdrop description: Local development server (Svelte) - url: https://flowdrop.ddev.site/api/flowdrop description: Local Drupal server security: - BearerAuth: [] - SessionAuth: [] tags: - name: System description: System health and status endpoints - name: Node Types description: Node type discovery and metadata endpoints - name: Configuration description: System configuration endpoints including port configuration - name: Workflows description: Workflow CRUD operations - name: Pipeline description: Pipeline execution and monitoring - name: Playground description: Interactive workflow testing and chat interface - name: Interrupts description: | Human-in-the-Loop (HITL) interrupt endpoints for workflow interactions. Interrupts allow workflows to pause execution and request user input. - name: Validation description: Workflow validation - name: Import/Export description: Workflow import and export operations - name: Chat description: | LLM Chat Interface for natural language workflow building. Translates user intent into DSL commands via a backend LLM integration. - name: Agent Spec description: > Oracle Open Agent Spec integration endpoints. Provides bidirectional conversion between FlowDrop workflows and Agent Spec format, plus runtime execution on compatible runtimes (WayFlow, PyAgentSpec). @see https://github.com/oracle/agent-spec paths: /workflows/import/agentspec: post: tags: - Agent Spec - Import/Export summary: Import workflow from Agent Spec JSON description: > Convert an Agent Spec flow or document to a FlowDrop workflow. The conversion: - Maps Agent Spec component types to FlowDrop node types - Merges control_flow_connections and data_flow_connections into unified edges - Auto-layouts nodes if no position metadata is present - Preserves Agent Spec component_type in FlowDrop extensions operationId: importWorkflowFromAgentSpec requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/AgentSpecFlow' - $ref: '#/components/schemas/AgentSpecDocument' responses: '200': description: Workflow imported successfully content: application/json: schema: $ref: '#/components/schemas/WorkflowResponse' '400': $ref: '#/components/responses/BadRequest' '422': description: Invalid Agent Spec format content: application/json: schema: $ref: '#/components/schemas/AgentSpecValidationResult' '500': $ref: '#/components/responses/InternalServerError' components: schemas: AgentSpecFlow: type: object description: > Agent Spec Flow — a directed, potentially cyclic graph of nodes. Flows function as "subroutines" encapsulating repeatable processes. They separate control-flow (execution order) from data-flow (data routing). properties: component_type: type: string enum: - flow name: type: string description: Flow name example: document_processing description: type: string description: Human-readable description start_node: type: string description: Reference to the StartNode name example: start nodes: type: array items: $ref: '#/components/schemas/AgentSpecNode' description: All nodes in the flow control_flow_connections: type: array items: $ref: '#/components/schemas/AgentSpecControlFlowEdge' description: Execution order edges data_flow_connections: type: array nullable: true items: $ref: '#/components/schemas/AgentSpecDataFlowEdge' description: | Data routing edges. When null, data flows by matching input/output property names across connected nodes. metadata: type: object additionalProperties: true description: Extension metadata required: - component_type - name - start_node - nodes - control_flow_connections AgentSpecDocument: type: object description: | Top-level Agent Spec document. Contains a flow and/or agent definition along with shared tool and LLM configuration declarations. properties: agent: $ref: '#/components/schemas/AgentSpecAgent' flow: $ref: '#/components/schemas/AgentSpecFlow' tools: type: array items: $ref: '#/components/schemas/AgentSpecTool' description: Shared tool declarations llm_configs: type: array items: $ref: '#/components/schemas/AgentSpecLLMConfig' description: Shared LLM configurations metadata: type: object additionalProperties: true description: Document-level metadata WorkflowResponse: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/Workflow' AgentSpecValidationResult: type: object description: Result of validating a workflow for Agent Spec export properties: valid: type: boolean description: Whether the workflow is valid for Agent Spec export errors: type: array items: type: string description: Validation errors (must be fixed before export) warnings: type: array items: type: string description: Validation warnings (may affect runtime behavior) required: - valid AgentSpecNode: description: | Union of all Agent Spec node types. Discriminated by `component_type`. oneOf: - $ref: '#/components/schemas/AgentSpecStartNode' - $ref: '#/components/schemas/AgentSpecEndNode' - $ref: '#/components/schemas/AgentSpecLLMNode' - $ref: '#/components/schemas/AgentSpecAPINode' - $ref: '#/components/schemas/AgentSpecAgentNode' - $ref: '#/components/schemas/AgentSpecFlowNode' - $ref: '#/components/schemas/AgentSpecMapNode' - $ref: '#/components/schemas/AgentSpecBranchingNode' - $ref: '#/components/schemas/AgentSpecToolNode' discriminator: propertyName: component_type mapping: start_node: $ref: '#/components/schemas/AgentSpecStartNode' end_node: $ref: '#/components/schemas/AgentSpecEndNode' llm_node: $ref: '#/components/schemas/AgentSpecLLMNode' api_node: $ref: '#/components/schemas/AgentSpecAPINode' agent_node: $ref: '#/components/schemas/AgentSpecAgentNode' flow_node: $ref: '#/components/schemas/AgentSpecFlowNode' map_node: $ref: '#/components/schemas/AgentSpecMapNode' branching_node: $ref: '#/components/schemas/AgentSpecBranchingNode' tool_node: $ref: '#/components/schemas/AgentSpecToolNode' AgentSpecControlFlowEdge: type: object description: | Control flow edge — defines execution order between nodes. Multiple control flow connections from the same branch are prohibited. properties: name: type: string description: Edge name (identifier) example: start_to_process from_node: type: string description: Source node name example: start to_node: type: string description: Target node name example: process_input from_branch: type: string nullable: true description: Source branch name (null = default "next" branch) example: high_priority required: - name - from_node - to_node AgentSpecDataFlowEdge: type: object description: | Data flow edge — routes data between node outputs and inputs. Maps a specific output property of a source node to a specific input property of a destination node. properties: name: type: string description: Edge name (identifier) example: query_to_llm source_node: type: string description: Source node name example: process_input source_output: type: string description: Source output property title example: processed_text destination_node: type: string description: Destination node name example: llm_generate destination_input: type: string description: Destination input property title example: prompt required: - name - source_node - source_output - destination_node - destination_input AgentSpecAgent: type: object description: | Agent Spec Agent — top-level conversational AI system. Serves as the entry point and holds shared resources like tools, memory, and LLM configuration. properties: component_type: type: string enum: - agent name: type: string description: Agent name example: customer_support_agent description: type: string description: Human-readable description inputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' outputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' tools: type: array items: oneOf: - $ref: '#/components/schemas/AgentSpecTool' - type: string description: Component reference string description: Available tools (inline or $component_ref strings) llm_config: description: LLM configuration (inline or $component_ref string) oneOf: - $ref: '#/components/schemas/AgentSpecLLMConfig' - type: string system_prompt: type: string description: System prompt template metadata: type: object additionalProperties: true required: - component_type - name AgentSpecTool: description: Union of all Agent Spec tool types oneOf: - $ref: '#/components/schemas/AgentSpecServerTool' - $ref: '#/components/schemas/AgentSpecClientTool' - $ref: '#/components/schemas/AgentSpecRemoteTool' discriminator: propertyName: component_type mapping: server_tool: $ref: '#/components/schemas/AgentSpecServerTool' client_tool: $ref: '#/components/schemas/AgentSpecClientTool' remote_tool: $ref: '#/components/schemas/AgentSpecRemoteTool' AgentSpecLLMConfig: type: object description: LLM model configuration properties: component_type: type: string enum: - llm_config name: type: string description: Configuration name example: gpt4_config model_id: type: string description: Model identifier (e.g., "gpt-4o", "claude-sonnet-4-5-20250929") example: gpt-4o provider: type: string description: Provider name (e.g., "openai", "anthropic") example: openai url: type: string description: API endpoint URL parameters: type: object additionalProperties: true description: Generation parameters (temperature, max_tokens, etc.) example: temperature: 0.7 max_tokens: 2048 metadata: type: object additionalProperties: true required: - component_type - name - model_id ApiResponse: type: object properties: success: type: boolean description: Whether the request was successful data: description: Response data (type varies by endpoint) message: type: string description: Response message error: type: string description: Error message (if any) Workflow: type: object properties: id: type: string format: uuid description: Workflow UUID name: type: string description: Workflow name example: My AI Workflow maxLength: 200 description: type: string description: Workflow description maxLength: 1000 nodes: type: array items: $ref: '#/components/schemas/WorkflowNode' description: Workflow nodes edges: type: array items: $ref: '#/components/schemas/WorkflowEdge' description: Workflow edges metadata: $ref: '#/components/schemas/WorkflowMetadata' config: type: object description: >- Custom workflow-level configuration values. Populated when a workflowSettingsSchema is provided to the editor. additionalProperties: true required: - id - name - nodes - edges - metadata ErrorResponse: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: success: type: boolean example: false error: type: string description: Error message code: type: string description: Error code details: type: object description: Additional error details AgentSpecStartNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - start_node description: Graph entry point node AgentSpecEndNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - end_node description: Graph exit point node AgentSpecLLMNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - llm_node llm_config: description: LLM configuration (inline object or $component_ref string) oneOf: - $ref: '#/components/schemas/AgentSpecLLMConfig' - type: string description: Component reference (e.g., "$component_ref:my_llm") system_prompt: type: string description: System prompt template (supports {{variable}} syntax) prompt_template: type: string description: User prompt template (supports {{variable}} syntax) output_schema: type: object additionalProperties: true description: Output JSON Schema for structured output description: LLM text generation node AgentSpecAPINode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - api_node endpoint: type: string description: API endpoint URL example: https://api.example.com/v1/data method: type: string description: HTTP method enum: - GET - POST - PUT - DELETE - PATCH example: POST headers: type: object additionalProperties: type: string description: Request headers body: type: object additionalProperties: true description: Request body template description: HTTP API call node AgentSpecAgentNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - agent_node agent: description: Agent reference ($component_ref or inline) oneOf: - $ref: '#/components/schemas/AgentSpecAgent' - type: string description: Multi-round agent conversation node AgentSpecFlowNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - flow_node flow: description: Flow reference ($component_ref or inline) oneOf: - $ref: '#/components/schemas/AgentSpecFlow' - type: string description: Nested flow execution node AgentSpecMapNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - map_node input_collection: type: string description: Input collection property name output_collection: type: string description: Output collection property name map_flow: description: Flow or node to execute per item ($component_ref or inline) oneOf: - $ref: '#/components/schemas/AgentSpecFlow' - type: string description: Map-reduce operation node AgentSpecBranchingNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - branching_node branches: type: array items: $ref: '#/components/schemas/AgentSpecBranch' description: Branch definitions with conditions required: - branches description: Conditional routing node AgentSpecToolNode: allOf: - $ref: '#/components/schemas/AgentSpecNodeBase' - type: object properties: component_type: type: string enum: - tool_node tool: description: Tool reference ($component_ref or inline) oneOf: - $ref: '#/components/schemas/AgentSpecServerTool' - $ref: '#/components/schemas/AgentSpecClientTool' - $ref: '#/components/schemas/AgentSpecRemoteTool' - type: string description: Tool execution node AgentSpecProperty: type: object description: > JSON Schema-based input/output property definition. Uses JSON Schema types and structure for describing data shape. Placeholder syntax `{{variable_name}}` generates implicit input properties. properties: title: type: string description: Property name (used as identifier in edges and templates) example: user_query type: type: string description: JSON Schema type example: string enum: - string - number - integer - boolean - array - object description: type: string description: Human-readable description default: description: Default value enum: type: array items: {} description: Allowed values (JSON Schema enum) items: $ref: '#/components/schemas/AgentSpecProperty' description: Array item schema (for type=array) properties: type: object additionalProperties: $ref: '#/components/schemas/AgentSpecProperty' description: Object property schemas (for type=object) required: type: array items: type: string description: Required properties (for type=object) required: - title - type AgentSpecServerTool: type: object description: Tool executed in the same runtime environment properties: component_type: type: string enum: - server_tool name: type: string description: Tool name example: web_search description: type: string description: Human-readable description inputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' outputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' function_name: type: string description: Function name or module path example: tools.web_search metadata: type: object additionalProperties: true required: - component_type - name AgentSpecClientTool: type: object description: Tool executed by the client, results returned to runtime properties: component_type: type: string enum: - client_tool name: type: string description: Tool name description: type: string inputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' outputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' metadata: type: object additionalProperties: true required: - component_type - name AgentSpecRemoteTool: type: object description: Tool triggered via RPC/REST calls properties: component_type: type: string enum: - remote_tool name: type: string description: Tool name description: type: string inputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' outputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' endpoint: type: string description: Remote endpoint URL method: type: string description: HTTP method headers: type: object additionalProperties: type: string description: Request headers metadata: type: object additionalProperties: true required: - component_type - name WorkflowNode: type: object description: | Represents a node instance in a workflow. Each node instance contains: - Position on the canvas - Display data (label) - Configuration values (config) - user-defined settings - Metadata from the node type definition - Optional execution state and extensions properties: id: type: string format: uuid description: Node instance UUID type: type: string description: Node type ID (references NodeMetadata.id) example: calculator position: $ref: '#/components/schemas/Position' deletable: type: boolean default: true data: type: object properties: label: type: string description: Node instance label example: Math Calculator config: $ref: '#/components/schemas/NodeConfig' metadata: $ref: '#/components/schemas/NodeMetadata' isProcessing: type: boolean description: Whether the node is currently processing error: type: string description: Error message if node execution failed nodeId: type: string description: Alternative node ID executionInfo: $ref: '#/components/schemas/NodeExecutionInfo' extensions: $ref: '#/components/schemas/NodeExtensions' description: > Per-instance extension properties for 3rd party integrations. Overrides or extends the node type extensions defined in metadata.extensions. Use for instance-specific UI states or custom data. Common use cases: - `extensions.ui.hideUnconnectedHandles`: Hide ports without connections - `extensions.ui.style`: Custom styling for this node instance required: - label - config - metadata required: - id - type - position - data WorkflowEdge: type: object properties: id: type: string format: uuid description: Edge UUID source: type: string format: uuid description: Source node UUID target: type: string format: uuid description: Target node UUID sourceHandle: type: string description: Source port ID targetHandle: type: string description: Target port ID type: type: string description: Connection line type enum: - default - straight - step - smoothstep selectable: type: boolean default: true deletable: type: boolean default: true data: type: object properties: label: type: string description: Edge label condition: type: string description: Conditional expression for conditional edges metadata: type: object description: Edge metadata for API and persistence properties: edgeType: type: string enum: - trigger - tool - data description: Edge type for visual styling sourcePortDataType: type: string description: >- Data type of the source output port (e.g., tool, string, number) isToolConnection: type: boolean description: >- Whether this is a tool connection (deprecated, use metadata.edgeType instead) targetNodeType: type: string description: Target node type targetCategory: type: string description: Target node category required: - id - source - target WorkflowMetadata: type: object properties: schemaVersion: type: string description: >- Workflow schema format version — identifies the document format, not the workflow's own revision. example: 1.0.0 createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp author: type: string description: Workflow author example: admin tags: type: array items: type: string description: Workflow tags example: - ai - production versionId: type: string description: Version control ID updateNumber: type: integer description: Update sequence number format: type: string description: | Workflow format identifier. Determines which node types are shown in the sidebar and how the workflow is exported. Built-in formats: 'flowdrop' (default), 'agentspec'. Custom formats can be registered via WorkflowFormatRegistry. example: flowdrop default: flowdrop required: - schemaVersion - createdAt - updatedAt AgentSpecNodeBase: type: object description: Base properties shared by all Agent Spec nodes properties: component_type: $ref: '#/components/schemas/AgentSpecNodeComponentType' name: type: string description: Node name (used as identifier in edges) example: process_input description: type: string description: Human-readable description inputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' description: Input properties outputs: type: array items: $ref: '#/components/schemas/AgentSpecProperty' description: Output properties metadata: type: object additionalProperties: true description: | Extension metadata. Includes FlowDrop-specific data for round-trip: - `flowdrop:position` — Node position `{x, y}` on the canvas - `flowdrop:dynamic` — Whether ports are dynamically configured required: - component_type - name AgentSpecBranch: type: object description: Branch definition for BranchingNode conditional routing properties: name: type: string description: Branch name (used as from_branch in ControlFlowEdge) example: high_priority condition: type: string description: Condition expression for this branch example: '{{priority}} == "high"' description: type: string description: Human-readable description required: - name Position: type: object properties: x: type: number description: X coordinate example: 100 'y': type: number description: Y coordinate example: 200 required: - x - 'y' NodeConfig: type: object description: > Node configuration values containing all user-configured settings for a node instance. This object stores configuration based on the node type's `configSchema` and is used by the backend to: - **Store and retrieve** node configuration persistently - **Pass values** to node processors during workflow execution - **Persist state** across sessions ## Standard Properties Any property defined in the node's `configSchema` (e.g., model, temperature, apiKey). The schema defines the type, validation rules, and default values for each property. ## Reserved Property Names These property names have special meaning and trigger automatic behaviors in FlowDrop: ### Instance Display Overrides - **`instanceTitle`**: Per-instance title override (replaces the default `label` display) - **`instanceDescription`**: Per-instance description override (replaces `metadata.description` display) - **`instanceBadge`**: Per-instance badge label override (replaces the default `metadata.badge` or "TOOL" badge) ### Visual Type Selection - **`nodeType`**: Changes the visual rendering type of the node (e.g., "default", "simple", "square") ### Dynamic Ports - **`dynamicInputs`**: Array of DynamicPort for user-defined input handles - **`dynamicOutputs`**: Array of DynamicPort for user-defined output handles - **`branches`**: Array of Branch for gateway node conditional output paths These dynamic configuration values generate additional handles on the node that can be connected to other nodes in the workflow. properties: instanceTitle: type: string description: > Per-instance title override that replaces the default node label. Useful when you have multiple instances of the same node type and want to give each a meaningful name (e.g., "Email Summarizer" instead of "LLM Processor"). Fallback behavior: - If `instanceTitle` is set → displays `instanceTitle` - If not set → displays `label` (from node data) example: Email Summarizer instanceDescription: type: string description: > Per-instance description override that replaces the default `metadata.description`. Useful for documenting what a specific node instance does within your workflow. Fallback behavior: - If `instanceDescription` is set → displays `instanceDescription` - If not set → displays `metadata.description` (from node type definition) example: Summarizes incoming emails into 3 bullet points instanceBadge: type: string description: | Per-instance badge label override for tool nodes. Replaces the default badge text shown in the node header. Fallback behavior: - If `instanceBadge` is set → displays `instanceBadge` - If not set → displays `metadata.badge` (from node type definition) - If neither set → displays "TOOL" example: API nodeType: type: string description: > Changes how the node is visually rendered. This allows a single node definition to support multiple visual representations. Available built-in types: - `default`: Standard workflow node with full details - `simple`: Compact layout with minimal chrome - `square`: Geometric square layout (icon-only) - `atom`: Minimal label-only pill/rectangle (uses extensions.ui.atom) - `tool`: Specialized style for agent tools - `gateway`: Branching control flow visualization - `terminal`: Start/end/exit node styling - `note`: Sticky note style for annotations - `idea`: Conceptual idea node for BPMN-like flow diagrams The node's `metadata.supportedTypes` defines which types are allowed. If invalid or missing, falls back to `metadata.type` or "default". enum: - default - simple - square - atom - tool - gateway - terminal - note - idea example: simple dynamicInputs: type: array items: $ref: '#/components/schemas/DynamicPort' description: >- User-defined dynamic input ports that appear as additional input handles dynamicOutputs: type: array items: $ref: '#/components/schemas/DynamicPort' description: >- User-defined dynamic output ports that appear as additional output handles branches: type: array items: $ref: '#/components/schemas/Branch' description: Gateway node branches that define conditional output paths additionalProperties: true example: instanceTitle: Email Summarizer instanceDescription: Summarizes incoming emails into 3 bullet points instanceBadge: LLM nodeType: simple model: gpt-4o-mini temperature: 0.7 maxTokens: 1000 apiKey: sk-... dynamicInputs: - name: extra_data label: Extra Data dataType: json required: false dynamicOutputs: - name: result label: Result dataType: string branches: - name: success label: Success condition: status === 200 - name: error label: Error isDefault: true NodeMetadata: type: object description: > Complete metadata for a node type including ports, configuration schema, and extensions. ## Dynamic Port Support Nodes can support user-defined dynamic ports through their configSchema: - Add `dynamicInputs` array property to allow custom input handles - Add `dynamicOutputs` array property to allow custom output handles - Add `branches` array property for gateway nodes with conditional paths ## Extensions Support The `extensions` property allows storing UI settings and 3rd party data: - Use `extensions.ui.hideUnconnectedHandles` to hide unconnected ports by default - Use namespaced keys for custom integrations (e.g., "myapp:settings") properties: id: type: string description: Node type unique identifier example: calculator name: type: string description: Node type display name example: Calculator type: $ref: '#/components/schemas/NodeType' supportedTypes: type: array items: $ref: '#/components/schemas/NodeType' description: Array of supported rendering types description: type: string description: Node type description example: Perform mathematical operations on input data category: $ref: '#/components/schemas/NodeCategory' version: type: string description: Node type version example: 1.0.0 icon: type: string description: Icon identifier (Material Design Icons) example: mdi:calculator color: type: string description: Node color (CSS color value) example: '#3b82f6' badge: type: string description: > Default badge label displayed in the node header (e.g., "TOOL", "API", "LLM"). Currently used by tool nodes. Can be overridden per-instance via `config.instanceBadge`. Defaults to "TOOL" for tool nodes if not specified. example: API portDataType: type: string description: > Port dataType to expose on tool nodes. Defaults to "tool". Set to another type (e.g., "trigger") to show that port type instead. This allows repurposing the tool node with a custom badge and matching port type. example: trigger inputs: type: array items: $ref: '#/components/schemas/NodePort' description: | Static input ports defined by the node type. Additional dynamic inputs can be added via config.dynamicInputs. outputs: type: array items: $ref: '#/components/schemas/NodePort' description: | Static output ports defined by the node type. Additional dynamic outputs can be added via config.dynamicOutputs. For gateway nodes, branches create additional output handles. configSchema: $ref: '#/components/schemas/ConfigSchema' tags: type: array items: type: string description: Node tags for search and filtering example: - math - calculation - processing formats: type: array items: type: string description: | Workflow formats this node is compatible with. When omitted, the node is universal (compatible with all formats). When specified, the node only appears in the sidebar for workflows matching one of the listed formats. example: - agentspec extensions: $ref: '#/components/schemas/NodeExtensions' description: > Default extension properties for all instances of this node type. Can be overridden at the instance level via WorkflowNode.data.extensions. required: - id - name - description - category - version - inputs - outputs NodeExecutionInfo: type: object properties: status: $ref: '#/components/schemas/NodeExecutionStatus' executionCount: type: integer description: Total number of times this node has been executed example: 5 lastExecuted: type: string format: date-time description: Last execution timestamp lastExecutionDuration: type: integer description: Last execution duration in milliseconds example: 1500 lastError: type: string description: Last error message if execution failed isExecuting: type: boolean description: Whether the node is currently being executed required: - status - executionCount - isExecuting NodeExtensions: type: object description: > Custom extension properties for 3rd party integrations. Allows storing additional configuration and UI state data. Use namespaced keys (e.g., "myapp:analytics", "acme:settings") to avoid conflicts between different integrations. ## Reserved Extension Keys - `agentspec:component_type` — Stores the Oracle Open Agent Spec component type (e.g., "llm_node", "branching_node") for nodes imported from Agent Spec. Used for round-trip preservation during import/export. properties: ui: $ref: '#/components/schemas/NodeUIExtensions' agentspec:component_type: type: string description: | Agent Spec component type for round-trip preservation. Set automatically when importing from Agent Spec format. example: llm_node additionalProperties: true example: ui: hideUnconnectedHandles: true style: opacity: 0.8 agentspec:component_type: llm_node myapp:analytics: trackUsage: true customField: value AgentSpecNodeComponentType: type: string enum: - start_node - end_node - llm_node - api_node - agent_node - flow_node - map_node - branching_node - tool_node description: | Agent Spec node component_type discriminator. Determines the node's behavior and available configuration: - `start_node` — Graph entry point - `end_node` — Graph exit point - `llm_node` — LLM text generation - `api_node` — HTTP API call - `agent_node` — Multi-round agent conversation - `flow_node` — Nested flow execution - `map_node` — Map-reduce operation - `branching_node` — Conditional routing - `tool_node` — Tool execution DynamicPort: type: object description: > Dynamic port configuration for user-defined inputs/outputs. These are defined in the node's config and allow users to create custom input/output handles at runtime, similar to gateway branches. Dynamic ports are stored in `config.dynamicInputs` and `config.dynamicOutputs` arrays and are rendered alongside static ports defined in the node metadata. properties: name: type: string description: Unique identifier for the port (used for handle IDs and connections) example: custom_input_1 label: type: string description: Display label shown in the UI example: Custom Input description: type: string description: Description of what this port accepts/provides example: Additional input data for processing dataType: $ref: '#/components/schemas/NodeDataType' description: Data type for the port (affects color and connection validation) required: type: boolean default: false description: Whether this port is required for execution required: - name - label - dataType example: name: custom_data label: Custom Data description: Additional JSON data input dataType: json required: false Branch: type: object description: > Branch configuration for gateway nodes. Branches define conditional output paths in gateway/switch nodes. Each branch creates an output handle that can be connected to downstream nodes. Branches are stored in `config.branches` array and support dynamic addition/removal through the node configuration panel. properties: name: type: string description: Unique identifier for the branch (used as handle ID) example: case_1 label: type: string description: Display label shown in the UI example: Case 1 description: type: string description: Description of when this branch is activated example: Triggered when condition A is met condition: type: string description: Optional condition expression for this branch example: value > 10 isDefault: type: boolean default: false description: Whether this is the default/fallback branch required: - name - label example: name: high_priority label: High Priority description: Route for high priority items condition: priority === 'high' isDefault: false NodeType: type: string enum: - note - simple - square - atom - tool - gateway - terminal - idea - default description: > Visual rendering type for the node. Built-in types: - `note` - Sticky note with markdown support - `simple` - Compact layout with header and description - `square` - Minimal square node with centered icon - `atom` - Minimal label-only pill/rectangle for value/transform nodes (uses extensions.ui.atom) - `tool` - Specialized node for agent tools - `gateway` - Branching control flow with dynamic branches (uses config.branches) - `terminal` - Circular node for workflow start/end/exit points - `idea` - Conceptual idea node for BPMN-like flow diagrams - `default` - Full-featured workflow node with dynamic port support ## Dynamic Port Support The `default` and `gateway` node types support dynamic ports: - **default**: Supports `config.dynamicInputs` and `config.dynamicOutputs` for user-defined input/output handles - **gateway**: Supports `config.branches` for conditional branching paths ## UI Extensions All node types support `extensions.ui.hideUnconnectedHandles` to control visibility of unconnected ports. NodeCategory: type: string description: | Node category for organizing nodes in the sidebar. Any string value is accepted, allowing custom categories. Custom categories can be defined via the `/categories` endpoint with display labels, icons, and colors. Built-in categories with dedicated icons and colors: triggers, inputs, outputs, prompts, models, processing, logic, data, tools, helpers, vector stores, embeddings, memories, agents, ai, interrupts, bundles example: processing NodePort: type: object description: > Defines an input or output port on a node. Ports are connection points where data flows between nodes. Input ports receive data from upstream nodes, and output ports send data to downstream nodes. ## Template Variable Autocomplete Output ports can include a `schema` property that describes the structure of their data. This schema is used by downstream nodes' template fields to provide autocomplete suggestions. When a template field is connected to a port with a schema, users get: - Autocomplete for top-level properties when typing `{{` - Nested property drilling when typing `.` - Array index suggestions when typing `[` properties: id: type: string description: Port unique identifier (used in handle IDs and variable names) example: json name: type: string description: Port display name shown in the UI example: JSON Response type: type: string enum: - input - output - metadata description: Port direction (input receives data, output sends data) dataType: $ref: '#/components/schemas/NodeDataType' required: type: boolean default: false description: Whether the port must be connected for the node to execute description: type: string description: Help text describing what data the port expects or provides example: Parsed JSON response from the HTTP request defaultValue: description: Default value used when no connection provides data schema: $ref: '#/components/schemas/PortDataSchema' description: > JSON Schema describing the structure of data on this output port. **Purpose:** Enables template variable autocomplete in downstream nodes. When a downstream node has a template field connected to this port, the schema's properties become available as autocomplete suggestions. **How it works:** 1. Define a schema with `properties` on an output port 2. Connect this port to a downstream node's input 3. In the downstream node's template field, typing `{{` shows the schema's properties **Example:** ```yaml outputs: - id: json name: JSON Response type: output dataType: json schema: type: object properties: user: type: object properties: name: { type: string } email: { type: string } orders: type: array items: type: object properties: id: { type: string } total: { type: number } ``` This enables autocomplete for: - `{{ user }}`, `{{ orders }}` - `{{ user.name }}`, `{{ user.email }}` - `{{ orders[0].id }}`, `{{ orders[0].total }}` required: - id - name - type - dataType ConfigSchema: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: $ref: '#/components/schemas/ConfigProperty' description: Configuration properties required: type: array items: type: string description: Required property names additionalProperties: type: boolean default: false required: - type - properties NodeExecutionStatus: type: string enum: - idle - pending - running - completed - failed - cancelled - skipped - paused - interrupted description: Current execution status of a node NodeUIExtensions: type: object description: > UI-related extension settings for nodes. Used to control visual behavior in the workflow editor. These settings can be defined at two levels: 1. **Node Type Level** (`metadata.extensions.ui`): Default settings for all instances 2. **Instance Level** (`data.extensions.ui`): Override for specific node instances Instance-level settings take precedence over type-level defaults. properties: hideUnconnectedHandles: type: boolean description: | Show/hide unconnected handles (ports) to reduce visual noise. When true, only ports with active connections are displayed. Useful for nodes with many optional ports. example: true atom: $ref: '#/components/schemas/AtomUIConfig' style: type: object additionalProperties: true description: Custom styles or theme overrides example: opacity: 0.8 borderRadius: 8 additionalProperties: true NodeDataType: type: string description: | Data type for node ports. The available data types are configured dynamically through the port configuration system. example: mixed PortDataSchema: type: object description: > JSON Schema describing the structure of data on an output port. Follows JSON Schema draft-07 specification. ## Purpose Enables template variable autocomplete in downstream nodes by describing the shape of data that flows through the port. ## Supported Features - **Objects**: Define `properties` to enable dot notation drilling - **Arrays**: Define `items` to enable index access and item property drilling - **Nested structures**: Combine objects and arrays for deep drilling - **Metadata**: Use `title` and `description` for autocomplete tooltips ## Example A schema describing an API response with user data and orders: ```yaml type: object properties: user: type: object title: User description: The authenticated user properties: id: { type: integer } name: { type: string, description: "User's full name" } email: { type: string } address: type: object properties: city: { type: string } country: { type: string } orders: type: array title: Orders description: User's order history items: type: object properties: order_id: { type: string } total: { type: number } status: { type: string } ``` This enables template patterns like: - `{{ user.name }}` - Access user's name - `{{ user.address.city }}` - Nested property access - `{{ orders[0].total }}` - First order's total - `{{ orders[0].status }}` - First order's status properties: type: type: string enum: - object - array - string - number - integer - boolean description: | The JSON Schema type. Use `object` for nested properties, `array` for lists with `items` schema. title: type: string description: | Human-readable title shown in autocomplete dropdown. If not provided, the property name is used. description: type: string description: | Description shown as tooltip in autocomplete. Helps users understand what data the property contains. properties: type: object additionalProperties: $ref: '#/components/schemas/PortDataSchema' description: Property schemas for object types items: $ref: '#/components/schemas/PortDataSchema' description: Item schema for array types required: type: array items: type: string description: Required property names example: type: object properties: user: type: object title: User description: User information properties: id: type: integer description: User ID name: type: string description: User full name email: type: string description: User email address address: type: object title: Address properties: street: type: string city: type: string country: type: string orders: type: array title: Orders description: List of user orders items: type: object properties: order_id: type: string product_name: type: string quantity: type: integer price: type: number ConfigProperty: type: object description: > JSON Schema property definition for node configuration. Follows JSON Schema draft-07 specification with FlowDrop extensions for UI rendering. For select/dropdown fields, use standard JSON Schema patterns: - `enum` for simple value lists (no labels) - `oneOf` with `const`/`title` for labeled options properties: type: type: string enum: - string - number - boolean - array - object - integer description: JSON Schema type title: type: string description: Display title for the property description: type: string description: Property description default: description: Default value for the property enum: type: array items: {} description: | Allowed values for enum properties (simple values without labels). For labeled options, use `oneOf` with `const`/`title` instead. oneOf: type: array items: $ref: '#/components/schemas/OneOfItem' description: > JSON Schema oneOf for labeled options (standard approach). Each item should have `const` (value) and optionally `title` (label). Example: ```json "oneOf": [ { "const": "draft", "title": "Draft" }, { "const": "published", "title": "Published" } ] ``` multiple: type: boolean description: >- For enum/oneOf fields, allows multiple selection (renders as checkbox group) minimum: type: number description: Minimum value for numeric properties maximum: type: number description: Maximum value for numeric properties step: type: number description: Step increment for number/range inputs minLength: type: integer description: Minimum length for string properties maxLength: type: integer description: Maximum length for string properties pattern: type: string description: Regex pattern for string validation placeholder: type: string description: Placeholder text for input fields format: type: string description: > Special format hints for UI rendering: - `multiline`: Renders as textarea - `hidden`: Field is hidden from UI but included in form submission - `range`: Renders as range slider for numeric values - `json`: Renders as CodeMirror JSON editor - `code`: Alias for json, renders as CodeMirror editor - `markdown`: Renders as SimpleMDE Markdown editor - `template`: Template editor with variable autocomplete (see below) - `autocomplete`: Text input with callback URL suggestions - `email`, `uri`, `date`, `date-time`: Standard JSON Schema formats ## Template Format Details The `template` format renders a CodeMirror editor with: **Syntax highlighting** for Twig/Liquid-style `{{ variable }}` placeholders **Inline autocomplete** triggered by: - Typing `{{` - Shows available variables - Typing `.` after an object - Shows nested properties - Typing `[` after an array - Shows index suggestions **Variable patterns supported:** - `{{ user }}` - Simple variable - `{{ user.name }}` - Nested property access - `{{ user.address.city }}` - Deep nesting - `{{ items[0] }}` - Array index access - `{{ orders[0].product.name }}` - Combined patterns **Autocomplete source:** Variables are derived from connected upstream nodes that have output schemas defined. Use the `variables` property to configure which input ports provide variables. enum: - multiline - hidden - range - json - code - markdown - template - autocomplete - email - uri - date - date-time variables: $ref: '#/components/schemas/TemplateVariablesConfig' description: | Configuration for template variable autocomplete. Only applicable when `format: "template"`. See TemplateVariablesConfig for full documentation. x-display-order: type: integer description: > Controls the display order of fields in the configuration form. Fields are sorted by this value in ascending order (lower values appear first). Use negative values to ensure fields appear at the top: - `-2` for `instanceTitle` (appears first) - `-1` for `instanceDescription` (appears second) - `0` or positive values for regular fields Fields without `x-display-order` are sorted after fields with explicit ordering. example: -2 items: $ref: '#/components/schemas/ConfigProperty' description: Schema for array items minItems: type: integer description: Minimum number of items for array fields maxItems: type: integer description: Maximum number of items for array fields properties: type: object additionalProperties: $ref: '#/components/schemas/ConfigProperty' description: Property schemas for object fields autocomplete: $ref: '#/components/schemas/AutocompleteConfig' description: >- Configuration for autocomplete fields (when format is "autocomplete") readOnly: type: boolean description: > JSON Schema `readOnly` keyword. When true, the field is displayed but cannot be edited (rendered in a disabled state). height: type: string description: | Editor height as a CSS value (e.g. `200px`). Applies to editor fields: `json`/`code`, `markdown`, and `template`. Defaults: `200px` (code), `300px` (markdown), `250px` (template). example: 300px darkTheme: type: boolean description: | Force the editor's dark theme on or off. Applies to `json`/`code` and `template` fields. When omitted, the editor follows the resolved app theme. autoFormat: type: boolean default: true description: | Whether to auto-format JSON on blur. Applies to `json`/`code` editor fields. showToolbar: type: boolean default: true description: | Whether to show the editor toolbar. Applies to `markdown` editor fields. showStatusBar: type: boolean default: true description: | Whether to show the editor status bar. Applies to `markdown` editor fields. spellChecker: type: boolean default: false description: | Whether to enable spell checking. Applies to `markdown` editor fields. placeholderExample: type: string description: | Example template string shown as a placeholder hint. Applies to `template` fields. example: 'Hello {{ name }}, your order #{{ order_id }} is ready!' required: - type AtomUIConfig: type: object description: > Display/behaviour settings for minimalist `atom` nodes (e.g. Constant, Cast). Lives under `extensions.ui.atom`. The atom renderer reads these to decide what to show, and `valueTypeKey` drives the bound output port's `dataType` from config so connection validation matches the type the user picked. All fields are optional — an empty object renders a label-only pill using the node's `label`. properties: valueKey: type: string description: | Config key whose value becomes the node body text. Falls back to the node `label` when unset or empty. example: value valueTypeKey: type: string description: | Config key holding the selected value's type (a port dataType id). The bound output port adopts this dataType. example: valueType outputPortId: type: string description: | Output port id driven by `valueTypeKey`. Defaults to the first output port when unset. example: value shape: type: string enum: - pill - rectangle default: pill description: > Body shape. `pill` (default) is fully rounded; `rectangle` is lightly rounded. example: rectangle prefix: type: string description: > Dimmed affordance rendered before the body (e.g. `"→ "` to mark a transform). Stays visible while the body value ellipsizes. Hidden in the empty state. example: '→ ' placeholder: type: string description: Text shown (dimmed) when the resolved body value is empty/unset. example: empty maxWidth: type: integer description: Max body width in px before the label ellipsizes. example: 200 additionalProperties: false OneOfItem: type: object description: | JSON Schema oneOf item for labeled options. This is the standard JSON Schema way to define labeled select options. Example: ```json { "type": "string", "oneOf": [ { "const": "draft", "title": "Draft" }, { "const": "published", "title": "Published" } ] } ``` properties: const: oneOf: - type: string - type: number - type: boolean description: The constant value for this option (JSON Schema `const` keyword) title: type: string description: Human-readable label for this option description: type: string description: Optional description for this option required: - const TemplateVariablesConfig: type: object description: > Configuration for template variable autocomplete in template fields. ## Overview When a template field is connected to upstream nodes that have output schemas, FlowDrop automatically derives available variables for autocomplete. This config controls which ports provide variables and how they are presented. ## Variable Derivation Variables are derived from connected upstream nodes' **output port schemas**. When an output port has a `schema` property with `properties`, those properties become available as template variables. ### Default Behavior (includePortName: false) Schema properties are **unpacked as top-level variables**: ``` HTTP Request node (output port "json" with schema): schema.properties: { user: {...}, orders: {...} } ↓ Template variables: {{ user }}, {{ orders }} ``` ### With includePortName: true Variables are **prefixed with the port name**: ``` Same schema as above: ↓ Template variables: {{ data.user }}, {{ data.orders }} ``` ## Nested Property Access The autocomplete supports drilling into nested structures: - **Dot notation**: `{{ user.address.city }}` - **Array indices**: `{{ orders[0].product_name }}` - **Combined**: `{{ user.orders[0].items[1].price }}` properties: ports: type: array items: type: string description: > Specifies which input port IDs should provide variables for autocomplete. Only connections to these ports will contribute variables. **Behavior:** - If not specified: All input ports with connections are used - If empty array `[]`: No variables derived from ports (use with `schema` for static variables) - If specified: Only the listed ports contribute variables **Example:** A node with inputs "data", "context", and "trigger": - `ports: ["data"]` - Only variables from the "data" connection - `ports: ["data", "context"]` - Variables from both connections - Not specified - Variables from all non-trigger connections example: - data - context schema: $ref: '#/components/schemas/VariableSchema' description: > Pre-defined variable schema to provide static variables or override derived ones. When both `ports` and `schema` are specified, variables are **merged**: - Variables from connected ports are computed first - Static `schema` variables are added/override existing ones **Use cases:** - Provide variables that don't come from connections - Override labels or descriptions for derived variables - Add custom variables for specific use cases includePortName: type: boolean default: false description: | Controls how variables are named when derived from port schemas. **When false (default):** Schema properties become top-level variables directly. A port with schema `{ user: {...}, orders: {...} }` produces: - `{{ user }}` - `{{ orders }}` **When true:** Variables are prefixed with the input port name. Same schema connected to input port "data" produces: - `{{ data.user }}` - `{{ data.orders }}` **When to use true:** - Multiple input ports with potentially overlapping property names - You want to be explicit about data sources in templates - Backward compatibility with existing templates showHints: type: boolean default: true description: > Whether to display clickable variable hints below the editor. When enabled, shows a row of buttons for top-level variables that users can click to insert `{{ variableName }}` at the cursor position. Disable if the variable list is too long or not useful. example: ports: - data showHints: true includePortName: false AutocompleteConfig: type: object description: > Configuration for autocomplete fields that fetch suggestions from a callback URL. Used when format is "autocomplete". properties: url: type: string description: | The callback URL to fetch autocomplete suggestions from. Can be relative (resolved against API base URL) or absolute. example: /api/users/search queryParam: type: string default: q description: Query parameter name to pass the search term minChars: type: integer default: 0 description: | Minimum number of characters before fetching suggestions. Set to 0 to fetch immediately on focus (when fetchOnFocus is true). debounceMs: type: integer default: 300 description: Debounce delay in milliseconds before fetching suggestions fetchOnFocus: type: boolean default: false description: Whether to fetch all options when the field is focused labelField: type: string default: label description: The field name in the response objects to use as the display label valueField: type: string default: value description: The field name in the response objects to use as the stored value allowFreeText: type: boolean default: false description: | Whether to allow values that are not in the suggestions list. When true, users can enter and submit any text. multiple: type: boolean default: false description: | Whether to allow multiple selections. When true, users can select multiple values displayed as tags. params: type: object additionalProperties: type: string description: | Map of URL query parameter names to sibling form field names. When fetching autocomplete options, the current value of each referenced sibling field is appended as a query parameter. When any dependency field changes, the autocomplete clears its current value and invalidates the suggestion cache. required: - url VariableSchema: type: object description: | Schema passed to template editor for autocomplete functionality. Contains all available variables derived from connected upstream nodes. This is computed by the frontend based on: 1. Finding all edges that connect to the current node's input ports 2. Getting the output schemas from the source nodes' output ports 3. Building a hierarchical variable structure for autocomplete properties: variables: type: object additionalProperties: $ref: '#/components/schemas/TemplateVariable' description: Map of available variables keyed by variable name required: - variables example: variables: user: name: user type: object label: User Data properties: name: name: name type: string email: name: email type: string items: name: items type: array label: Order Items items: name: item type: object properties: product_name: name: product_name type: string price: name: price type: number TemplateVariable: type: object description: | Represents a variable available for template interpolation. Used by the template editor for autocomplete suggestions. Supports hierarchical drilling: - Objects have `properties` for dot notation (e.g., `user.name`) - Arrays have `items` for index access (e.g., `items[0].name`) properties: name: type: string description: Variable name (used in template as {{ name }}) example: user label: type: string description: Display label for the variable in autocomplete dropdown example: User Data description: type: string description: Description shown in autocomplete tooltip example: User information from upstream node type: type: string enum: - string - number - integer - boolean - array - object - float - mixed description: Data type of the variable properties: type: object additionalProperties: $ref: '#/components/schemas/TemplateVariable' description: For objects - child properties accessible via dot notation items: $ref: '#/components/schemas/TemplateVariable' description: For arrays - schema of array items accessible via index notation sourcePort: type: string description: Source port ID this variable comes from sourceNode: type: string description: Source node ID required: - name - type example: name: user label: User Data type: object properties: name: name: name type: string label: User Name email: name: email type: string label: Email Address address: name: address type: object label: Address properties: city: name: city type: string label: City country: name: country type: string label: Country responses: BadRequest: description: Bad request - invalid parameters or request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Invalid request parameters code: VALIDATION_ERROR details: field: name message: Name is required InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Internal server error code: INTERNAL_ERROR securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token for authentication SessionAuth: type: apiKey in: cookie name: SESS description: Drupal session cookie ````