# REST API Reference

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

!!! info "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](bc-policy.md#rest-api-stability) for details.

## Base URL

All paths below are relative to `/api/flowdrop`.

## Response Format

All responses use a consistent envelope:

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

Error responses:

```json
{
  "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

| Method | Path | Description |
|--------|------|-------------|
| POST | `/session/{sessionId}/turn` | Execute a chat turn: post a user message and run the session's workflow on it (202 + turn handle). See [Session Turns & Events](session-turn-events.md) |

### 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`](../../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.
