REST API Reference¶

FlowDrop exposes a RESTful JSON API under /api/flowdrop/. All endpoints require Drupal authentication (session or Bearer token) unless noted otherwise.

Stability

REST API endpoints are stable in 1.x. Existing paths and response fields will not change. New fields may be added (additive-only). See the BC Policy for details.

Base URL¶

All paths below are relative to /api/flowdrop.

Response Format¶

All responses use a consistent envelope:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "details": { ... }
}

Endpoints¶

System¶

Method	Path	Description
GET	`/health`	API health check (no auth required)

Node Types¶

Method	Path	Description
GET	`/nodes`	List all available node types. Supports `?category=` and `?search=` filters
GET	`/nodes/{id}`	Get a specific node type by plugin ID

Port Configuration¶

Method	Path	Description
GET	`/port-config`	Get port compatibility rules and data type definitions

Workflows¶

Method	Path	Description
GET	`/workflows`	List all workflows
POST	`/workflows`	Create a new workflow
GET	`/workflows/{id}`	Get a workflow by ID (includes nodes and edges)
PUT	`/workflows/{id}`	Update a workflow
DELETE	`/workflows/{id}`	Delete a workflow
POST	`/workflows/validate`	Validate a workflow definition
GET	`/workflows/{id}/export`	Export a workflow as JSON
POST	`/workflows/import`	Import a workflow from JSON

Pipeline Execution¶

Method	Path	Description
GET	`/workflow/{workflow_id}/pipelines`	List pipelines for a workflow
GET	`/pipeline/{id}`	Get pipeline execution details (includes job status)
POST	`/pipeline/{id}/execute`	Execute a pipeline
POST	`/pipeline/{id}/stop`	Stop a running pipeline
GET	`/pipeline/{id}/logs`	Get pipeline execution logs

Playground¶

Method	Path	Description
GET	`/workflows/{id}/playground/sessions`	List playground sessions for a workflow
POST	`/workflows/{id}/playground/sessions`	Create a new playground session
GET	`/playground/sessions/{sessionId}`	Get session details
DELETE	`/playground/sessions/{sessionId}`	Delete a session
GET	`/playground/sessions/{sessionId}/messages`	Get messages from a session
POST	`/playground/sessions/{sessionId}/messages`	Send a message to the session
GET	`/playground/sessions/{sessionId}/messages/{messageId}`	Get a single message
GET	`/playground/sessions/{sessionId}/messages/{messageId}/status`	Get message processing status
POST	`/playground/sessions/{sessionId}/stop`	Stop playground execution

OpenAPI Specification¶

The full OpenAPI 3.0 specification is available at docs/development/api/openapi.yaml. You can use it with tools like Swagger UI or Redoc for interactive documentation.

Authentication¶

API endpoints require one of:

Session authentication — Standard Drupal session cookie (for browser-based access)
Bearer token — Authorization: Bearer <token> header (for programmatic access)

The /health endpoint is the only exception and requires no authentication.