---
name: flowise-api
description: Manages Flowise AI instances via REST API. Performs CRUD operations on chatflows, agentflows (V2/V3), assistants, custom tools, variables, and document stores. Sends predictions (chat messages) with streaming, file uploads, and human-in-the-loop support. Queries vector stores and manages feedback/leads. Uses bearer token authentication. Triggers on "flowise", "chatflow", "agentflow", "prediction", "send message to flow", "document store", "vector upsert", "flowise API".
license: MIT
compatibility: Requires Python 3.8+. Works with Claude Code, OpenCode, Cursor, Copilot, and other Agent Skills compatible agents.
metadata:
  author: crottolo
  version: "1.0.0"
---

# Flowise API Skill

## Golden Rule: AUTHENTICATE → DISCOVER → EXECUTE

**Never interact with a Flowise instance without first verifying authentication works.**
Every interaction follows this mandatory flow:

1. **AUTHENTICATE** — Set credentials and test connectivity with `health_check.py`
2. **DISCOVER** — List available chatflows, assistants, tools, and variables
3. **EXECUTE** — Perform the requested operation with confidence

## Credentials Contract

Set these environment variables before using any script:

```bash
export FLOWISE_BASE_URL="<your-flowise-url>"      # Flowise instance URL
export FLOWISE_API_KEY="<your-api-key>"            # API key from Flowise dashboard
```

**Security note**: Never hardcode credentials in scripts or commits. Use environment variables or a secrets manager.

Or pass them as flags: `--base-url URL --api-key KEY`

### How to get the API key

1. Open Flowise dashboard → **Settings** → **API Keys**
2. A default key is auto-created; copy it or create a new one
3. Assign the key to specific chatflows via **Chatflow Settings** → **Security**

### Two authentication levels

| Level              | Scope                                                         | Header                                     |
| ------------------ | ------------------------------------------------------------- | ------------------------------------------ |
| **App-level**      | All management APIs (chatflows, assistants, tools, variables) | `Authorization: Bearer <jwt-token>`        |
| **Chatflow-level** | Prediction endpoint only (`/prediction/{id}`)                 | `Authorization: Bearer <chatflow-api-key>` |

## Scripts

All scripts are in `scripts/`. They use `flowise_client.py` as shared HTTP client.

### Step 0: Test Authentication (run FIRST)

```bash
python scripts/health_check.py
# Tests: ping → chatflows → assistants → variables → tools
# If any FAIL → fix credentials before proceeding
```

### Chatflow & AgentFlow Operations

```bash
# List all chatflows (CHATFLOW + MULTIAGENT types)
python scripts/chatflows.py list

# List only agentflows (V2/V3)
python scripts/chatflows.py list --type MULTIAGENT

# Get chatflow details (includes flowData with all nodes)
python scripts/chatflows.py get FLOW_ID

# Create a new chatflow
python scripts/chatflows.py create --name "My Bot" --type CHATFLOW --deployed

# Create an agentflow (V2/V3)
python scripts/chatflows.py create --name "My Agent" --type MULTIAGENT --deployed

# Update chatflow
python scripts/chatflows.py update FLOW_ID --name "New Name" --deployed true

# Update chatbot widget config
python scripts/chatflows.py update FLOW_ID --chatbot-config '{"welcomeMessage":"Ciao!"}'

# Delete chatflow
python scripts/chatflows.py delete FLOW_ID
```

### Assistant Operations

```bash
# List all assistants
python scripts/assistants.py list

# Get assistant details
python scripts/assistants.py get ASST_ID

# Create assistant
python scripts/assistants.py create \
  --name "Sales Assistant" \
  --model gpt-4 \
  --instructions "You are a sales expert..." \
  --temperature 0.7 \
  --tools code_interpreter retrieval

# Update assistant
python scripts/assistants.py update ASST_ID --name "Updated Name" --model gpt-4o

# Delete assistant
python scripts/assistants.py delete ASST_ID
```

### Send Predictions (Chat Messages)

```bash
# Simple question (non-streaming)
python scripts/prediction.py FLOW_ID "What is AI?"

# Streaming response (SSE)
python scripts/prediction.py FLOW_ID "Tell me a story" --streaming

# With conversation continuity
python scripts/prediction.py FLOW_ID "Tell me more" --chat-id "session-123"

# With override config
python scripts/prediction.py FLOW_ID "Analyze this" \
  --override '{"temperature":0.2,"modelName":"gpt-4o"}'

# With file upload
python scripts/prediction.py FLOW_ID "Describe this image" \
  --upload-file image.png --upload-type file:full

# With conversation history
python scripts/prediction.py FLOW_ID "Continue" \
  --history '[{"role":"userMessage","content":"Hi"},{"role":"apiMessage","content":"Hello!"}]'

# Human-in-the-loop: resume execution
python scripts/prediction.py FLOW_ID "" \
  --human-input proceed --human-feedback "OK, continue"
```

### Chat Message History

```bash
# List messages for a chatflow
python scripts/messages.py list FLOW_ID

# Filter by chat session
python scripts/messages.py list FLOW_ID --chat-id "session-123" --order ASC

# Filter by date range
python scripts/messages.py list FLOW_ID --start-date "2025-01-01" --end-date "2025-12-31"

# Filter by feedback
python scripts/messages.py list FLOW_ID --feedback true --feedback-type THUMBS_UP

# Delete messages (soft delete)
python scripts/messages.py delete FLOW_ID --chat-id "session-123"

# Hard delete (also from third-party services)
python scripts/messages.py delete FLOW_ID --hard-delete
```

### Document Store Operations

```bash
# List all document stores
python scripts/documents.py list

# Get store details
python scripts/documents.py get STORE_ID

# Create document store
python scripts/documents.py create --name "Product Docs" --description "Product documentation"

# Upsert documents with full pipeline config
python scripts/documents.py upsert STORE_ID \
  --loader '{"name":"pdfFile","config":{}}' \
  --splitter '{"name":"recursiveCharacterTextSplitter","config":{"chunkSize":1000,"chunkOverlap":200}}' \
  --embedding '{"name":"openAIEmbeddings","config":{"modelName":"text-embedding-3-small"}}' \
  --vector-store '{"name":"pinecone","config":{"index":"my-index"}}'

# Query vector store
python scripts/documents.py query STORE_ID "How does the product work?"

# Get chunks
python scripts/documents.py chunks STORE_ID LOADER_ID --page 1

# Re-process all documents
python scripts/documents.py refresh STORE_ID

# Delete store
python scripts/documents.py delete STORE_ID

# Delete vector store data only
python scripts/documents.py delete-vector STORE_ID
```

### Variable Operations

```bash
# List all variables
python scripts/variables.py list

# Create variable
python scripts/variables.py create --name "MY_VAR" --value "my-value" --type string

# Update variable
python scripts/variables.py update VAR_ID --value "new-value"

# Delete variable
python scripts/variables.py delete VAR_ID
```

### Custom Tool Operations

```bash
# List all tools
python scripts/tools.py list

# Get tool details (includes schema and function code)
python scripts/tools.py get TOOL_ID

# Create custom tool with JavaScript function
python scripts/tools.py create \
  --name "web_scraper" \
  --description "Scrapes web pages" \
  --schema '{"type":"object","properties":{"url":{"type":"string"}}}' \
  --func 'const resp = await fetch($url); return await resp.text();'

# Update tool
python scripts/tools.py update TOOL_ID --name "updated_scraper"

# Delete tool
python scripts/tools.py delete TOOL_ID
```

### Feedback Operations

```bash
# List feedback for a chatflow
python scripts/feedback.py list FLOW_ID

# Filter by date range
python scripts/feedback.py list FLOW_ID --start-date "2025-01-01" --end-date "2025-12-31"

# Create feedback (thumbs up/down on a message)
python scripts/feedback.py create \
  --chatflow-id FLOW_ID \
  --chat-id CHAT_ID \
  --message-id MSG_ID \
  --rating THUMBS_UP \
  --content "Great answer!"

# Update feedback
python scripts/feedback.py update FEEDBACK_ID --rating THUMBS_DOWN --content "Changed my mind"
```

### Lead Capture Operations

```bash
# List leads for a chatflow
python scripts/leads.py list FLOW_ID

# Create a lead
python scripts/leads.py create \
  --chatflow-id FLOW_ID \
  --chat-id CHAT_ID \
  --name "Mario Rossi" \
  --email "mario@example.com" \
  --phone "+39123456789"
```

## Key Concepts

### Chatflow vs AgentFlow

| Type          | `type` value | Description                                                                |
| ------------- | ------------ | -------------------------------------------------------------------------- |
| **Chatflow**  | `CHATFLOW`   | Linear flow: prompt → LLM → response                                       |
| **AgentFlow** | `MULTIAGENT` | Multi-agent: V2/V3 with tool routing, conditional logic, human-in-the-loop |

Both are managed via the same `/chatflows` endpoints. The `type` field distinguishes them.

### flowData Structure

The `flowData` field is a JSON string containing all nodes, edges, and configurations.
To inspect a flow's internal structure:

```bash
# Get raw flowData
python scripts/chatflows.py get FLOW_ID | python -c "
import sys,json
flow = json.load(sys.stdin)
data = json.loads(flow.get('flowData','{}'))
for node in data.get('nodes',[]):
    print(f\"  [{node.get('type','')}] {node.get('data',{}).get('label','')} (id: {node.get('id','')})\")
"
```

### Upload Types

| Type        | Use Case                                                     |
| ----------- | ------------------------------------------------------------ |
| `file:full` | Full file content sent to LLM (summarization, analysis)      |
| `file:rag`  | File processed via RAG (chunking + embedding into vector DB) |
| `file`      | Generic file attachment                                      |
| `audio`     | Audio file for speech-to-text                                |
| `url`       | URL to fetch and process                                     |

### Streaming Events (SSE)

When `--streaming` is used, the response is Server-Sent Events.
Flowise uses a non-standard format: `data:{"event":"token","data":"text chunk"}`

| Event             | Data          | Description                  |
| ----------------- | ------------- | ---------------------------- |
| `start`           | empty         | Stream initialized           |
| `token`           | text chunk    | Incremental AI response      |
| `sourceDocuments` | JSON array    | RAG source documents         |
| `usedTools`       | JSON array    | Tools invoked                |
| `metadata`        | JSON object   | chatId, messageId, sessionId |
| `end`             | empty         | Stream complete              |
| `error`           | error message | Error occurred               |

## Error Codes

| Code | Meaning           | Action                               |
| ---- | ----------------- | ------------------------------------ |
| 400  | Invalid input     | Check request body format            |
| 401  | Unauthorized      | Check API key; regenerate if expired |
| 404  | Not found         | Verify ID exists via list command    |
| 413  | Payload too large | Reduce file size or chunk data       |
| 422  | Validation error  | Check required fields                |
| 500  | Server error      | Check Flowise logs                   |

## Workflow Examples

### "I want to test if my Flowise instance is reachable and auth works"

```bash
# 1. AUTHENTICATE: set credentials
export FLOWISE_BASE_URL="<your-flowise-url>"
export FLOWISE_API_KEY="<your-api-key>"

# 2. TEST: run health check
python scripts/health_check.py
# → Tests ping, chatflows, assistants, variables, tools
# → If all OK, auth is working
```

### "I want to create an agentflow and send it a message"

```bash
# 1. DISCOVER: list existing flows
python scripts/chatflows.py list --type MULTIAGENT

# 2. EXECUTE: create agentflow
python scripts/chatflows.py create --name "Support Agent" --type MULTIAGENT --deployed

# 3. Note the ID from output, then send a message
python scripts/prediction.py FLOW_ID "Help me with my order"
```

### "I want to set up RAG with a document store"

```bash
# 1. Create document store
python scripts/documents.py create --name "Knowledge Base"

# 2. Upsert documents with embedding pipeline
python scripts/documents.py upsert STORE_ID \
  --loader '{"name":"pdfFile","config":{}}' \
  --splitter '{"name":"recursiveCharacterTextSplitter","config":{"chunkSize":1000}}' \
  --embedding '{"name":"openAIEmbeddings","config":{}}' \
  --vector-store '{"name":"pinecone","config":{"index":"kb-index"}}'

# 3. Test query
python scripts/documents.py query STORE_ID "What is our refund policy?"
```

### "I want to manage credentials for multiple accounts"

```bash
# Account 1 (production)
FLOWISE_BASE_URL="$PROD_URL" FLOWISE_API_KEY="$PROD_KEY" \
  python scripts/chatflows.py list

# Account 2 (staging)
FLOWISE_BASE_URL="$STAGING_URL" FLOWISE_API_KEY="$STAGING_KEY" \
  python scripts/chatflows.py list

# Or use flags
python scripts/chatflows.py list --base-url "$PROD_URL" --api-key "$PROD_KEY"
```

## Reference Files

- [reference/api_endpoints.md](reference/api_endpoints.md) — Complete specification of all 35+ REST endpoints
- [reference/prediction_patterns.md](reference/prediction_patterns.md) — Advanced prediction patterns: streaming, uploads, overrideConfig, human-in-the-loop