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
POST	`/workflow/{workflow_id}/run`	Launch a workflow run with schema-resolved inputs (202 + pipeline ID)
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

Sessions¶

One session, addressed by its UUID, whichever client created it (flowdrop_session). Reads need view on the session, DELETE needs delete, and turn, stop and reset need update plus the execute session workflow permission. An unknown UUID is a 404 with error_code: NOT_FOUND.

Method	Path	Description
GET	`/sessions/{sessionId}`	Get the session row
DELETE	`/sessions/{sessionId}`	Delete the session and its messages
GET	`/sessions/{sessionId}/messages`	Page the messages: `since`, `before`, `latest`, `limit`; answers `{success, data, hasMore, hasOlder, sessionStatus}`
POST	`/sessions/{sessionId}/turn`	Take a turn: `{content?, inputs?}`, 202 + the turn result. See Session Turns & Events
POST	`/sessions/{sessionId}/stop`	Stop the running turn (409 `EXECUTION_NOT_RUNNING` when none runs)
POST	`/sessions/{sessionId}/reset`	Reset a stuck session to idle: `{session, resetCount}`
GET	`/sessions/{sessionId}/interrupts`	List the session's pending interrupts

Playground¶

Listing and creating sessions for a workflow is the Playground's:

Method	Path	Description
GET	`/workflows/{id}/playground/sessions`	List playground sessions for a workflow
POST	`/workflows/{id}/playground/sessions`	Create a new playground session

Deprecated, removed in 3.0. These paths still answer, with a Deprecation header and a Link to their successor:

Method	Path	Use instead
GET, DELETE	`/playground/sessions/{sessionId}`	`/sessions/{sessionId}`
GET	`/playground/sessions/{sessionId}/messages`	`/sessions/{sessionId}/messages`
POST	`/playground/sessions/{sessionId}/messages`	`/sessions/{sessionId}/turn` (answers the turn result, 202, not the user's row)
GET	`/playground/sessions/{sessionId}/messages/{messageId}` and `…/status`	`/sessions/{sessionId}/messages`
POST	`/playground/sessions/{sessionId}/stop`, `…/reset`	`/sessions/{sessionId}/stop`, `…/reset`
GET	`/playground/sessions/{sessionId}/interrupts`	`/sessions/{sessionId}/interrupts`
POST	`/session/{id}/turn` (entity id)	`/sessions/{sessionId}/turn` (UUID)

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.