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

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)
Enum: "triggers" "inputs" "outputs" "prompts" "models" "processing" "logic" "data" "tools" "helpers" "vector stores" "embeddings" "memories" "agents" "ai" "bundles"

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"
}

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

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)

Responses

Request samples

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

Response samples

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

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": {
    }
}

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)

Responses

Request samples

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

Response samples

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