> ## 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. # Execute an Agent Spec flow > Submit an Agent Spec flow for execution on the configured runtime (WayFlow, PyAgentSpec, or other compatible runtimes). The flow is posted as Agent Spec JSON. The runtime returns an execution ID for tracking progress via polling or WebSocket. ## OpenAPI ````yaml /api-reference/openapi.yaml post /agentspec/flows/execute 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: /agentspec/flows/execute: post: tags: - Agent Spec summary: Execute an Agent Spec flow description: | Submit an Agent Spec flow for execution on the configured runtime (WayFlow, PyAgentSpec, or other compatible runtimes). The flow is posted as Agent Spec JSON. The runtime returns an execution ID for tracking progress via polling or WebSocket. operationId: agentSpecExecuteFlow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentSpecExecutionRequest' responses: '200': description: Flow execution started successfully content: application/json: schema: $ref: '#/components/schemas/AgentSpecExecutionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: AgentSpecExecutionRequest: type: object description: Request to execute an Agent Spec flow on a runtime properties: flow: $ref: '#/components/schemas/AgentSpecFlow' inputs: type: object additionalProperties: true description: Initial input values for the flow example: user_query: What is the weather today? required: - flow AgentSpecExecutionResponse: type: object description: Response after starting an Agent Spec execution properties: execution_id: type: string description: Unique execution ID from the runtime example: exec-abc-123 id: type: string description: Alternative execution ID field status: type: string enum: - running - completed - failed - cancelled description: Initial execution status required: - execution_id 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 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 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 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) 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 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 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 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 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 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 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 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 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' 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 Unauthorized: description: Unauthorized - authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Authentication required code: UNAUTHORIZED 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 ````