API docs by Redocly

FlowDrop™ API (1.0.0)

Download OpenAPI specification:

FlowDrop Support: shibinkidd@gmail.com URL: https://www.drupal.org/project/issues/flowdrop?categories=All

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.

System

System health and status endpoints

API health check

Check if the FlowDrop API is running and responsive. This endpoint is at the root level following industry conventions for Kubernetes liveness/readiness probes and load balancer health checks.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "version": "1.0.0",
  • "service": "FlowDrop API",
  • "uptime": 3600
}

Get system configuration

Retrieve public system configuration settings

Authorizations:
BearerAuthSessionAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Get API version

Retrieve the current API version information

Responses

Response samples

Content type
application/json
{
  • "version": "1.0.0",
  • "build": "2026.01.26",
  • "api_version": "v1"
}

Node Types

Node type discovery and metadata endpoints

Get all available node types

Retrieve all available node processors with optional filtering by category, search query, and pagination. Supports filtering by node category (models, data_processing, input_output, etc.) and search queries.

Authorizations:
BearerAuthSessionAuth
query Parameters
category
string (NodeCategory)
Example: category=processing

Filter by node category

search
string <= 100 characters

Search node types by name, description, or tags

limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of results (1-1000)

offset
integer >= 0
Default: 0

Number of results to skip for pagination

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "Found 1 node types"
}

Get node type by ID

Retrieve detailed metadata for a specific node type by its unique identifier

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string
Example: calculator

Node type unique identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Configuration

System configuration endpoints including port configuration

Get port configuration

Retrieve the complete port configuration system including available data types, compatibility rules, and default settings. This configuration determines how nodes can be connected in workflows based on port data types.

Authorizations:
BearerAuthSessionAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "Port configuration loaded successfully"
}

Get category definitions

Retrieve all available category definitions including display labels, icons, colors, and ordering. Categories determine how nodes are organized in the sidebar.

Built-in categories are always available as defaults. This endpoint allows overriding built-in category metadata and defining custom categories.

Authorizations:
BearerAuthSessionAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "Categories loaded successfully"
}

Workflows

Workflow CRUD operations

Get all workflows

Retrieve all workflows with optional search filtering and pagination. Returns workflow metadata including nodes, edges, and execution history.

Authorizations:
BearerAuthSessionAuth
query Parameters
search
string <= 100 characters

Search workflows by name or description

tags
string

Filter by tags (comma-separated)

limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of workflows to return

offset
integer >= 0
Default: 0

Number of workflows to skip

sort
string
Default: "updated_at"
Enum: "created_at" "updated_at" "name"

Sort field

order
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string"
}

Create a new workflow

Create a new workflow with the provided name, description, nodes, and edges. The workflow will be assigned a unique UUID and metadata will be automatically generated.

Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters

Workflow name

description
string <= 1000 characters

Workflow description

Array of objects (WorkflowNode)
Array of objects (WorkflowEdge)
tags
Array of strings <= 20 items [ items <= 50 characters ]

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My First Workflow",
  • "description": "A simple workflow for testing",
  • "nodes": [ ],
  • "edges": [ ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Get workflow by ID

Retrieve a specific workflow with all its nodes, edges, and metadata

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Workflow UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Update workflow

Update an existing workflow. All fields are optional - only provided fields will be updated. The updatedAt timestamp will be automatically set to the current time.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters

Workflow name

description
string <= 1000 characters

Workflow description

Array of objects (WorkflowNode)
Array of objects (WorkflowEdge)
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "nodes": [
    ],
  • "edges": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Delete workflow

Permanently delete a workflow and all associated data including execution history

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Workflow deleted successfully"
}

Pipeline

Pipeline execution and monitoring

Execute workflow

Create a new pipeline and start execution in one call. This is a convenience endpoint that combines pipeline creation with immediate execution. Returns the pipeline ID and initial status for tracking.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

Request Body schema: application/json
optional
object

Input values for specific nodes

object

Responses

Request samples

Content type
application/json
{
  • "inputs": { },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

List execution history

Retrieve execution history across all workflows. Supports filtering by workflow, status, and date range.

Authorizations:
BearerAuthSessionAuth
query Parameters
workflow_id
string <uuid>

Filter by workflow UUID

status
string
Enum: "pending" "running" "completed" "failed" "cancelled"

Filter by execution status

limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of results

offset
integer >= 0
Default: 0

Number of results to skip

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string"
}

Get execution status

Retrieve the current status and details of a specific execution. This is an alias for the pipeline detail endpoint.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Execution/Pipeline UUID

Responses

Response samples

Content type
application/json
{
  • "status": "pending",
  • "jobs": [
    ],
  • "node_statuses": {
    },
  • "job_status_summary": {
    }
}

Cancel execution

Cancel a running execution. Only executions in 'pending' or 'running' status can be cancelled.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Execution/Pipeline UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Execution cancelled successfully"
}

Get execution logs

Retrieve detailed execution logs for a specific execution

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Execution/Pipeline UUID

query Parameters
level
string
Enum: "debug" "info" "warning" "error"

Filter by log level

node_id
string

Filter by node ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string"
}

List workflow pipelines

Get all pipeline executions for a specific workflow

Authorizations:
BearerAuthSessionAuth
path Parameters
workflow_id
required
string

Workflow ID or machine name

query Parameters
status
string
Enum: "pending" "running" "completed" "failed" "cancelled"

Filter by pipeline status

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string"
}

Get pipeline execution details

Retrieve detailed information about a pipeline execution including:

  • Overall pipeline status
  • Individual job statuses for each node
  • Node execution information (execution count, duration, errors)
  • Job status summary
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Pipeline UUID

Responses

Response samples

Content type
application/json
{
  • "status": "running",
  • "jobs": [
    ],
  • "node_statuses": {
    },
  • "job_status_summary": {
    }
}

Get pipeline status

Retrieve only the current status of a pipeline (lightweight endpoint). Use this for polling when you only need the status, not full details.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Pipeline UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Execute pipeline

Start execution of a pipeline

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Pipeline UUID

Request Body schema: application/json
optional
object

Input values for specific nodes

object

Responses

Request samples

Content type
application/json
{
  • "inputs": { },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Stop pipeline execution

Cancel a running pipeline execution

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Pipeline UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get pipeline execution logs

Retrieve detailed execution logs for a pipeline

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Pipeline UUID

query Parameters
level
string
Enum: "debug" "info" "warning" "error"

Filter by log level

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Playground

Interactive workflow testing and chat interface

List playground sessions for a workflow

Retrieve all playground sessions associated with a workflow. Sessions are used to test and interact with workflows in an isolated environment.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of sessions to return

offset
integer >= 0
Default: 0

Number of sessions to skip

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string"
}

Create a new playground session

Create a new playground session for testing a workflow. The session can be named for easy identification.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

Request Body schema: application/json
optional
name
string <= 100 characters

Optional session name

object

Optional metadata for the session

Responses

Request samples

Content type
application/json
{
  • "name": "Test Session 1",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Get playground session details

Retrieve detailed information about a specific playground session, including its current status and configuration.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Delete a playground session

Permanently delete a playground session and all its messages. This action cannot be undone.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Session deleted successfully"
}

Get messages from a playground session

Retrieve messages from a playground session with optional filtering. Supports polling via the since parameter to fetch only new messages.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

query Parameters
since
string <date-time>

ISO 8601 timestamp to fetch messages after this time. Used for polling to get only new messages.

limit
integer [ 1 .. 500 ]
Default: 100

Maximum number of messages to return

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string",
  • "hasMore": true,
  • "sessionStatus": "idle"
}

Send a message to the playground session

Send a user message or trigger workflow execution with inputs. This starts or continues the conversation in the playground.

The message is created with status "pending" and processing begins immediately (synchronously) or is queued (asynchronously) based on the session's execution mode. The response returns immediately with the message entity, allowing clients to poll the message status endpoint to track processing progress.

Messages are processed in sequence order within a session to ensure proper conversation flow. If a previous message is not yet complete, the request will be rejected with a conflict error.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

Request Body schema: application/json
required
content
required
string <= 10000 characters

Message content (typically user input)

object

Additional input values for workflow nodes

Responses

Request samples

Content type
application/json
Example
{
  • "content": "Hello, can you help me analyze this data?"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Get a single message

Retrieve a specific message from a playground session by its ID. Returns full message details including status and metadata.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

messageId
required
string <uuid>

Message UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Get message status

Retrieve only the status of a message (lightweight endpoint for polling). Useful for checking if message processing is complete without fetching full message data.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

messageId
required
string <uuid>

Message UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Stop playground execution

Stop the currently running execution in the playground session. This cancels any pending workflow operations.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Execution stopped"
}

Interrupts

Human-in-the-Loop (HITL) interrupt endpoints for workflow interactions. Interrupts allow workflows to pause execution and request user input.

Get interrupt details

Retrieve details about a specific interrupt request. Interrupts are created when a workflow execution requires human input.

Authorizations:
BearerAuthSessionAuth
path Parameters
interruptId
required
string <uuid>

Interrupt UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Resolve interrupt

Submit user response to resolve a pending interrupt. The value type depends on the interrupt type:

  • confirmation: boolean (true = confirmed)
  • choice: string or string[] (selected values)
  • text: string (user input)
  • form: object (form data matching schema)
Authorizations:
BearerAuthSessionAuth
path Parameters
interruptId
required
string <uuid>

Interrupt UUID

Request Body schema: application/json
required
value
required
any

User's response. Type depends on interrupt type:

  • confirmation: boolean
  • choice: string or string[]
  • text: string
  • form: object
  • review: ReviewResolution (decisions map + summary)

Responses

Request samples

Content type
application/json
Example
{
  • "value": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Cancel interrupt

Cancel a pending interrupt without providing a response. This may not be allowed for all interrupts - check the allowCancel property in the interrupt data before attempting to cancel.

Authorizations:
BearerAuthSessionAuth
path Parameters
interruptId
required
string <uuid>

Interrupt UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Interrupt cancelled"
}

List session interrupts

List all interrupts associated with a playground session. Useful for displaying pending interrupts or reviewing interrupt history.

Authorizations:
BearerAuthSessionAuth
path Parameters
sessionId
required
string <uuid>

Playground session UUID

query Parameters
status
string
Enum: "pending" "resolved" "cancelled"

Filter by interrupt status

limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of interrupts to return

offset
integer >= 0
Default: 0

Number of interrupts to skip

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string"
}

List pipeline interrupts

List all interrupts associated with a pipeline execution. Useful for monitoring workflow progress and pending user actions.

Authorizations:
BearerAuthSessionAuth
path Parameters
pipelineId
required
string <uuid>

Pipeline UUID

query Parameters
status
string
Enum: "pending" "resolved" "cancelled"

Filter by interrupt status

limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of interrupts to return

offset
integer >= 0
Default: 0

Number of interrupts to skip

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "message": "string",
  • "error": "string"
}

Validation

Workflow validation

Validate workflow

Validate a workflow structure without saving it. Checks for:

  • Valid node connections and port compatibility
  • Required configuration fields
  • Circular dependencies
  • Orphaned nodes
  • Missing required inputs
Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
id
required
string <uuid>

Workflow UUID

name
required
string <= 200 characters

Workflow name

description
string <= 1000 characters

Workflow description

required
Array of objects (WorkflowNode)

Workflow nodes

required
Array of objects (WorkflowEdge)

Workflow edges

required
object (WorkflowMetadata)
object

Custom workflow-level configuration values. Populated when a workflowSettingsSchema is provided to the editor.

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "My AI Workflow",
  • "description": "string",
  • "nodes": [
    ],
  • "edges": [
    ],
  • "metadata": {
    },
  • "config": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Validate workflow for Agent Spec export

Check if a FlowDrop workflow can be exported as Agent Spec. Returns validation errors and warnings without performing the export.

Checks include:

  • Exactly one start node (terminal/trigger type)
  • At least one end node (terminal/output type)
  • Gateway nodes have branches defined
  • All nodes are reachable from start
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

Responses

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": [
    ],
  • "warnings": [
    ]
}

Import/Export

Workflow import and export operations

Export workflow

Export a workflow as JSON or YAML format

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

query Parameters
format
string
Default: "json"
Enum: "json" "yaml"

Export format

Responses

Response samples

Content type
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "My AI Workflow",
  • "description": "string",
  • "nodes": [
    ],
  • "edges": [
    ],
  • "metadata": {
    },
  • "config": { }
}

Import workflow

Import a workflow from JSON format. A new UUID will be assigned to the imported workflow.

Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
id
required
string <uuid>

Workflow UUID

name
required
string <= 200 characters

Workflow name

description
string <= 1000 characters

Workflow description

required
Array of objects (WorkflowNode)

Workflow nodes

required
Array of objects (WorkflowEdge)

Workflow edges

required
object (WorkflowMetadata)
object

Custom workflow-level configuration values. Populated when a workflowSettingsSchema is provided to the editor.

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "My AI Workflow",
  • "description": "string",
  • "nodes": [
    ],
  • "edges": [
    ],
  • "metadata": {
    },
  • "config": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Export workflow as Agent Spec JSON

Convert a FlowDrop workflow to Agent Spec format and return it.

The conversion:

  • Maps FlowDrop node types to Agent Spec component types
  • Splits unified edges into control_flow_connections and data_flow_connections
  • Stores FlowDrop-specific data (positions, dynamic ports) in metadata extensions
  • Validates the workflow for Agent Spec compatibility before export
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

query Parameters
format
string
Default: "flow"
Enum: "flow" "document"

Output format (document wraps flow with agent/tools/LLM config)

Responses

Response samples

Content type
application/json
Example
{
  • "component_type": "flow",
  • "name": "document_processing",
  • "description": "string",
  • "start_node": "start",
  • "nodes": [
    ],
  • "control_flow_connections": [
    ],
  • "data_flow_connections": [
    ],
  • "metadata": { }
}

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
Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
One of
component_type
required
string
Value: "flow"
name
required
string

Flow name

description
string

Human-readable description

start_node
required
string

Reference to the StartNode name

required
Array of any (AgentSpecNode)

All nodes in the flow

required
Array of objects (AgentSpecControlFlowEdge)

Execution order edges

Array of objects or null (AgentSpecDataFlowEdge)

Data routing edges. When null, data flows by matching input/output property names across connected nodes.

object

Extension metadata

Responses

Request samples

Content type
application/json
Example
{
  • "component_type": "flow",
  • "name": "document_processing",
  • "description": "string",
  • "start_node": "start",
  • "nodes": [
    ],
  • "control_flow_connections": [
    ],
  • "data_flow_connections": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Chat

LLM Chat Interface for natural language workflow building. Translates user intent into DSL commands via a backend LLM integration.

Send a chat message

Send a natural language message to the LLM chat backend for a specific workflow. The request includes the current workflow state and optional conversation history so the LLM can generate contextually relevant responses.

The LLM response may contain plain text explanations and/or DSL commands in ```flowdrop fenced code blocks. The frontend extracts and previews these commands before execution.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Workflow ID

Request Body schema: application/json
required
message
required
string

The user's natural language message

required
object

Serialized current workflow state including nodes and edges. This gives the LLM context about the current workflow being edited.

Array of objects (ChatHistoryMessage)

Optional conversation history for multi-turn context

Responses

Request samples

Content type
application/json
Example
{
  • "message": "Add a processing node called \"transform\"",
  • "workflowState": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get chat conversation history

Retrieve the conversation history for a workflow's chat session. Returns an array of messages with role (user/assistant) and content.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Clear chat conversation history

Clear the conversation history for a workflow's chat session. This resets the chat context, starting a fresh conversation.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found",
  • "code": "NOT_FOUND"
}

Agent Spec

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

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.

Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
required
object (AgentSpecFlow)

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).

object

Initial input values for the flow

Responses

Request samples

Content type
application/json
{
  • "flow": {
    },
  • "inputs": {
    }
}

Response samples

Content type
application/json
{
  • "execution_id": "exec-abc-123",
  • "id": "string",
  • "status": "running"
}

Get Agent Spec execution status

Retrieve the current status and per-node execution info for a running or completed Agent Spec execution.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Execution ID from the runtime

Responses

Response samples

Content type
application/json
{
  • "execution_id": "string",
  • "status": "running",
  • "execution_status": "string",
  • "node_statuses": {
    },
  • "nodes": {
    },
  • "error": "string",
  • "message": "string"
}

Cancel Agent Spec execution

Cancel a running Agent Spec execution. Only executions in 'running' status can be cancelled.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Execution ID from the runtime

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Execution cancelled successfully"
}

Get Agent Spec execution results

Retrieve the final results of a completed Agent Spec execution. Returns null/404 if the execution is still running or was cancelled.

Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Execution ID from the runtime

Responses

Response samples

Content type
application/json
{
  • "response": "The weather today is sunny with a high of 72°F.",
  • "confidence": 0.95
}

Stream Agent Spec execution updates (WebSocket)

WebSocket endpoint for real-time execution updates. Streams per-node status changes and execution events as they occur.

Protocol: WebSocket (upgrade from HTTP)

Messages sent by server:

  • {"type": "node_status", "node": "<name>", "status": {...}}
  • {"type": "execution_complete", "results": {...}}
  • {"type": "execution_error", "error": "<message>"}
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string

Execution ID from the runtime

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": "Resource not found",
  • "code": "NOT_FOUND"
}

Validate Agent Spec flow on runtime

Validate an Agent Spec flow specification against the runtime without executing it. Checks for structural correctness, valid node references, and property compatibility.

Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
component_type
required
string
Value: "flow"
name
required
string

Flow name

description
string

Human-readable description

start_node
required
string

Reference to the StartNode name

required
Array of any (AgentSpecNode)

All nodes in the flow

required
Array of objects (AgentSpecControlFlowEdge)

Execution order edges

Array of objects or null (AgentSpecDataFlowEdge)

Data routing edges. When null, data flows by matching input/output property names across connected nodes.

object

Extension metadata

Responses

Request samples

Content type
application/json
{
  • "component_type": "flow",
  • "name": "document_processing",
  • "description": "string",
  • "start_node": "start",
  • "nodes": [
    ],
  • "control_flow_connections": [
    ],
  • "data_flow_connections": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": [
    ]
}

List available agents on the runtime

Retrieve a list of agents registered on the Agent Spec runtime. These agents can be referenced by agent_node components.

Authorizations:
BearerAuthSessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available tools on the runtime

Retrieve a list of tools registered on the Agent Spec runtime. These tools can be referenced by tool_node components.

Authorizations:
BearerAuthSessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Check Agent Spec runtime health

Verify that the configured Agent Spec runtime is available and responding. Used to check connectivity before execution.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "version": "1.0.0",
  • "runtime": "wayflow"
}

Export workflow as Agent Spec JSON

Convert a FlowDrop workflow to Agent Spec format and return it.

The conversion:

  • Maps FlowDrop node types to Agent Spec component types
  • Splits unified edges into control_flow_connections and data_flow_connections
  • Stores FlowDrop-specific data (positions, dynamic ports) in metadata extensions
  • Validates the workflow for Agent Spec compatibility before export
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

query Parameters
format
string
Default: "flow"
Enum: "flow" "document"

Output format (document wraps flow with agent/tools/LLM config)

Responses

Response samples

Content type
application/json
Example
{
  • "component_type": "flow",
  • "name": "document_processing",
  • "description": "string",
  • "start_node": "start",
  • "nodes": [
    ],
  • "control_flow_connections": [
    ],
  • "data_flow_connections": [
    ],
  • "metadata": { }
}

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
Authorizations:
BearerAuthSessionAuth
Request Body schema: application/json
required
One of
component_type
required
string
Value: "flow"
name
required
string

Flow name

description
string

Human-readable description

start_node
required
string

Reference to the StartNode name

required
Array of any (AgentSpecNode)

All nodes in the flow

required
Array of objects (AgentSpecControlFlowEdge)

Execution order edges

Array of objects or null (AgentSpecDataFlowEdge)

Data routing edges. When null, data flows by matching input/output property names across connected nodes.

object

Extension metadata

Responses

Request samples

Content type
application/json
Example
{
  • "component_type": "flow",
  • "name": "document_processing",
  • "description": "string",
  • "start_node": "start",
  • "nodes": [
    ],
  • "control_flow_connections": [
    ],
  • "data_flow_connections": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "message": "string",
  • "error": "string"
}

Validate workflow for Agent Spec export

Check if a FlowDrop workflow can be exported as Agent Spec. Returns validation errors and warnings without performing the export.

Checks include:

  • Exactly one start node (terminal/trigger type)
  • At least one end node (terminal/output type)
  • Gateway nodes have branches defined
  • All nodes are reachable from start
Authorizations:
BearerAuthSessionAuth
path Parameters
id
required
string <uuid>

Workflow UUID

Responses

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": [
    ],
  • "warnings": [
    ]
}