> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /playground/sessions/{sessionId}/messages 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: /playground/sessions/{sessionId}/messages: post: tags: - Playground summary: Send a message to the playground session description: > 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. operationId: sendPlaygroundMessage parameters: - name: sessionId in: path description: Playground session UUID required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlaygroundMessageRequest' examples: chatMessage: summary: Simple chat message value: content: Hello, can you help me analyze this data? withInputs: summary: Message with additional inputs value: content: Process this file inputs: file_path: /data/input.csv options: format: csv headers: true responses: '200': description: Message sent and workflow execution started content: application/json: schema: $ref: '#/components/schemas/PlaygroundMessageResponse' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': description: Session is already executing content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalServerError' components: schemas: PlaygroundMessageRequest: type: object description: Request body for sending a message to the playground properties: content: type: string description: Message content (typically user input) maxLength: 10000 inputs: type: object additionalProperties: true description: Additional input values for workflow nodes required: - content PlaygroundMessageResponse: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/PlaygroundMessage' 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 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) PlaygroundMessage: type: object description: | A message in a playground session. Messages can be user inputs, assistant responses, system notifications, or execution logs. properties: id: type: string format: uuid description: Message unique identifier sessionId: type: string format: uuid description: Parent session ID role: $ref: '#/components/schemas/PlaygroundMessageRole' content: type: string description: Message content timestamp: type: string format: date-time description: Message timestamp status: $ref: '#/components/schemas/PlaygroundMessageStatus' sequenceNumber: type: integer description: > Incrementing sequence number for chronological ordering within a session. All messages (user, assistant, log) receive incrementing numbers (1, 2, 3, ...). Use this as the primary sort key for displaying messages in order. minimum: 1 parentMessageId: type: string format: uuid description: Parent message ID (for linking user message to assistant response) nullable: true executionId: type: string description: Workflow execution ID that generated this message nullable: true parentPipelineId: type: string description: > Execution ID of the parent pipeline when this message was produced by a nested sub-flow. `null` for top-level (main pipeline) messages. Unlike the display-only `hierarchy`, this is an authoritative nesting signal: clients use it to keep the main pipeline in focus and exclude sub-flow runs from the run-switcher. nullable: true rootPipelineId: type: string description: > Execution ID of the top-level pipeline this message ultimately belongs to. Equal to `executionId` for main-pipeline messages; for sub-flow messages it points to the main run that triggered the sub-flow. nullable: true nodeId: type: string description: Associated node ID (for log messages) nullable: true hierarchy: type: array description: | Ordered hierarchy path describing where this message sits (e.g. workflow > sub-workflow > iteration). Display-only; rendered as a chevron-separated trail. The server decides the depth and content. items: $ref: '#/components/schemas/MessageHierarchyItem' tags: type: array description: | Server-emitted classification chips. When present, the client renders exactly these tags — there is no client-side synthesis. items: $ref: '#/components/schemas/MessageTag' display: $ref: '#/components/schemas/PlaygroundMessageDisplay' description: | Optional layout hint. When omitted, the client picks a default based on the message role. metadata: type: object properties: level: $ref: '#/components/schemas/PlaygroundMessageLevel' duration: type: integer description: Execution duration in milliseconds nodeLabel: type: string description: Human-readable node label outputs: type: object additionalProperties: true description: Node output data additionalProperties: true description: Additional message metadata required: - id - sessionId - role - content - timestamp - status - sequenceNumber example: id: be4d854d-d6b3-4242-b2ea-0008b2e059bd sessionId: fe5304ea-f069-433f-b0bf-945975c0b806 role: user content: Hello. How are you? timestamp: '2026-01-19T10:03:32+01:00' status: completed sequenceNumber: 1 parentMessageId: null nodeId: null metadata: {} PlaygroundMessageRole: type: string enum: - user - assistant - system - log description: | Role of the message sender: - `user`: Message from the user - `assistant`: Response from the workflow/AI - `system`: System notifications - `log`: Execution log entries PlaygroundMessageStatus: type: string enum: - pending - processing - completed - failed description: | Processing status of the message: - `pending`: Message created, waiting to be processed - `processing`: Message is currently being processed - `completed`: Message processing completed successfully - `failed`: Message processing failed MessageHierarchyItem: type: object description: > A single node on a message's hierarchy path. Rendered in document order separated by chevrons. Display-only — this is not a navigation breadcrumb. properties: id: type: string description: Stable identifier (used for keying) label: type: string description: Display label icon: type: string description: Optional iconify icon id (e.g. "mdi:graph") required: - id - label MessageTag: type: object description: | A server-emitted classification chip rendered alongside a message. When a message specifies tags, the client renders exactly those — no client-side synthesis or augmentation. properties: id: type: string description: Stable identifier (used for keying) label: type: string description: Display label icon: type: string description: Optional iconify icon id color: $ref: '#/components/schemas/MessageTagColor' description: Defaults to "muted" if omitted variant: $ref: '#/components/schemas/MessageTagVariant' description: Defaults to "subtle" if omitted type: type: string description: | Free-form classifier the server may use for future grouping or filtering. The client treats this as opaque metadata. required: - id - label PlaygroundMessageDisplay: type: string enum: - bubble - log - notice - card description: | Layout hint chosen by the server. When omitted, the client defaults from the role: - `log` → `log` - `system` (with compactSystemMessages enabled) → `notice` - everything else → `bubble` Layouts: - `bubble` — chat bubble with avatar, header, body, optional footer containing hierarchy + tags - `log` — one-liner: icon · hierarchy · body · tags · timestamp - `notice` — compact centered notice - `card` — vertical: hierarchy (top), body (middle), tags (bottom) PlaygroundMessageLevel: type: string enum: - info - warning - error - debug description: Log level for log-type messages MessageTagColor: type: string enum: - muted - primary - success - warning - error - info description: Semantic color hook for a MessageTag MessageTagVariant: type: string enum: - subtle - solid - outline description: Visual emphasis style for a MessageTag 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 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Resource not found code: NOT_FOUND 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 ````