> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.yaml get /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: get: tags: - Playground summary: Get messages from a playground session description: | Retrieve messages from a playground session with optional filtering. Supports polling via the `since` parameter to fetch only new messages. operationId: listPlaygroundMessages parameters: - name: sessionId in: path description: Playground session UUID required: true schema: type: string format: uuid - name: since in: query description: > Sequence number cursor — returns only messages with sequenceNumber greater than this value (forward pagination). Used for efficient polling of the live conversation tail. Mutually exclusive with `before`. required: false schema: type: integer minimum: 0 - name: before in: query description: | Sequence number cursor for backward pagination — returns the page of messages with sequenceNumber LESS than this value, selecting the `limit` messages with the highest sequence numbers below the cursor (i.e. the page immediately older than the cursor). Used for "load older" on scroll-up. Mutually exclusive with `since`. required: false schema: type: integer minimum: 0 - name: latest in: query description: | When true, return the most recent `limit` messages (the conversation tail), ignoring `since` and `before`. Use for the initial load of a chat surface. Defaults to false, which preserves the legacy oldest-first behavior when no cursor is supplied. required: false schema: type: boolean default: false - name: limit in: query description: Maximum number of messages to return required: false schema: type: integer minimum: 1 maximum: 500 default: 100 responses: '200': description: Messages retrieved successfully content: application/json: schema: $ref: '#/components/schemas/PlaygroundMessagesResponse' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: PlaygroundMessagesResponse: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/PlaygroundMessage' hasMore: type: boolean description: | Whether more recent messages remain after this page (forward pagination via `since`). hasOlder: type: boolean description: > Whether older messages exist before the first message in this page. Set on `latest`/`before` (backward pagination) responses so a chat surface knows whether to keep loading on scroll-up. sessionStatus: $ref: '#/components/schemas/PlaygroundSessionStatus' description: Current session status (useful for polling) 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: {} PlaygroundSessionStatus: type: string enum: - idle - running - awaiting_input - completed - failed description: Current status of a playground session 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 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: 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 ````