Flowise api

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:

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)

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

Chatflow & AgentFlow Operations

# 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

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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 "[email protected]" \
  --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:

# 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"

# 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"

# 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"

# 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"

# 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 — Complete specification of all 35+ REST endpoints
• reference/prediction_patterns.md — Advanced prediction patterns: streaming, uploads, overrideConfig, human-in-the-loop