Self-improving AI Employees for everyone
Workflow JSON Schema
Related Documentation:
- Node Creation Guide - How to create new nodes (frontend definitions, backend handlers)
- CLAUDE.md - Project overview, key files, architecture patterns
Overview
The workflow JSON schema defines the structure and validation rules for workflow automation data. This document describes the schema format, validation, and usage examples.
Schema Structure
A workflow JSON document contains:
- Metadata: ID, name, timestamps, version
- Nodes: Array of workflow nodes with their types, positions, and parameters
- Edges: Array of connections between nodes
Complete Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Workflow",
"description": "A workflow automation definition containing nodes and connections",
"type": "object",
"required": ["id", "name", "slug", "nodes", "edges", "createdAt", "lastModified"],
"properties": {
"id": {
"type": "string",
"description": "Stable positive decimal application identity allocated atomically by the backend for new workflows. Existing legacy records are not migrated.",
"pattern": "^[1-9][0-9]*$"
},
"name": {
"type": "string",
"description": "Free-form display name (sidebar label, parameter panel).",
"minLength": 1,
"maxLength": 100
},
"slug": {
"type": "string",
"description": "Human-readable identifier (e.g. AI_Assistant_1). Derived from name via services.workflow_naming.next_available_slug. Mutable on rename — recomputed + propagated to the workspace dir; Temporal ids and cron Schedule IDs follow at the next Start (a running generation keeps the slug it started with). UNIQUE across active workflows.",
"pattern": "^[A-Za-z0-9]+(_[0-9]+)?$"
},
"nodes": {
"type": "array",
"items": { "$ref": "#/definitions/node" }
},
"edges": {
"type": "array",
"items": { "$ref": "#/definitions/edge" }
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"lastModified": {
"type": "string",
"format": "date-time"
},
"version": {
"type": "string",
"default": "1.0.0"
}
}
}
Supported Node Types
Authoritative count = the plugin registry: one self-contained folder (or file) per node under
server/nodes/<group>/— 140+ node types (live total:len(services.node_registry.NODE_METADATA)afterimport nodes, oruv run pytest --collect-only); 34 palette groups registered inserver/nodes/groups.py. A bareserver/nodes/**/__init__.pyglob overcounts because it also matches the group packages. The breakdown below is illustrative and grouped by category; do not rely on a hand-maintained total.
The canonical list of nodes lives in the backend plugin tree at
server/nodes/<category>/<node>/__init__.py; this section is a human-readable index.
Workflow Nodes (1 node)
start- Workflow entry point with initial data
Trigger Nodes (3 nodes)
webhookTrigger- Incoming HTTP webhook trigger at/webhook/{path}chatTrigger- Console message input triggertaskTrigger- Event-driven trigger for delegated child agent completion
Scheduler Nodes (2 nodes)
timer- Delay/wait before continuing (seconds, minutes, hours)cronScheduler- Recurring scheduled execution (seconds to months, timezone support)
AI Chat Model Nodes (13 nodes)
openaiChatModel- OpenAI GPT 4.x/5.x + reasoning models (o1/o3/o4 series)anthropicChatModel- Anthropic Claude 4.x with extended thinkinggeminiChatModel- Google Gemini 2.5/3 with thinking supportopenrouterChatModel- OpenRouter unified API (200+ models)groqChatModel- Groq ultra-fast inference (Llama, Qwen3, GPT-OSS)cerebrasChatModel- Cerebras custom AI hardware (Llama, Qwen)deepseekChatModel- DeepSeek V4 (deepseek-v4.1-flash, the default / deepseek-v4-pro / deepseek-v4-flash)kimiChatModel- Moonshot Kimi K3 (the default) / K2.6 / K2.7-codemistralChatModel- Mistral Large / Small / CodestralollamaChatModel- Local Ollama server (OpenAI-compat via{provider}_proxyURL)lmstudioChatModel- Local LM Studio server (OpenAI-compat via{provider}_proxyURL)sarvamChatModel- Sarvam AI, Indic-first (OpenAI-compat; ships no model-list route, sosupports_model_listing: false)openaiCompatibleChatModel- Any OpenAI-compatible server saved as a named endpoint (llama.cpp, vLLM, a LiteLLM proxy); itsendpointfield picks one (RFC-0003)
AI Agents and Memory (3 nodes)
aiAgent- Tool-calling agent loopchatAgent- Conversational agent (Zeenie) with skill supportsimpleMemory- Markdown-based conversation memory with optional vector DB
Specialized AI Agents (15 nodes)
Pre-configured agents for specific domains. All inherit AI_AGENT_PROPERTIES. See agent_architecture.md:
android_agent- Android device controlcoding_agent- Code execution (Python, JavaScript, TypeScript)web_agent- Web automation and scrapingtask_agent- Task management and schedulingsocial_agent- Social messaging (WhatsApp, Telegram)travel_agent- Location and mapstool_agent- Generic tool orchestrationproductivity_agent- Google Workspace workflowspayments_agent- Payment processingconsumer_agent- Customer supportautonomous_agent- Code Mode with agentic loopsorchestrator_agent- Team lead for multi-agent coordinationai_employee- Team lead (alternate UI/branding)rlm_agent- Recursive Language Model (REPL-based, dedicated handler)claude_code_agent- Claude Code SDK integration
AI Tool Nodes (9; nodes that connect to an agent's input-tools handle, not all under server/nodes/tool/)
Connect to AI Agent's input-tools handle:
masterSkill- Aggregates multiple skills with enable/disable togglescalculatorTool- Math operationscurrentTimeTool- Current date/time with timezoneduckduckgoSearch- DuckDuckGo web search (free, no API key)taskManager- Task creation and tracking toolcanvas- Pushed-content display board (paths / URLs / markdown notes)dataSource- Raw local data over workspace paths and operator-approved mountswriteTodos- Structured task-list planning with checklist renderingagentBuilder- Spawns tools, agents, and skills onto the canvas mid-execution
Search Nodes (3 dual-purpose)
Work as both workflow nodes and AI tools. Defined under server/nodes/search/<plugin>/__init__.py:
braveSearch- Brave Search APIserperSearch- Google SERP via Serper APIperplexitySearch- Perplexity Sonar with citations
Location Nodes (3 nodes, 2 dual-purpose)
gmaps_create- Google Maps creation with center, zoom, map typegmaps_locations- Geocoding (address to coordinates)gmaps_nearby_places- Google Places nearbySearch
Google Workspace Nodes (7 nodes)
Consolidated operation-based nodes sharing one OAuth connection. See new_service_integration.md:
googleGmail- send / search / read (dual-purpose)googleGmailReceive- Polling trigger for incoming emailsgoogleCalendar- create / list / update / deletegoogleDrive- upload / download / list / sharegoogleSheets- read / write / appendgoogleTasks- create / list / complete / update / deletegoogleContacts- create / list / search / get / update / delete
WhatsApp Nodes (3 nodes)
whatsappSend- Dual-purpose: send text/media/location/contact to contacts, groups, channelswhatsappDb- Dual-purpose: 18 operations covering chat history, contacts, groups, newsletterswhatsappReceive- Event-driven trigger with filters (type, sender, group, keywords, channel)
Twitter/X Nodes (4 nodes)
twitterSend- Dual-purpose: tweet, reply, retweet, like, deletetwitterSearch- Dual-purpose: rich search with expansions and citationstwitterUser- Dual-purpose: profiles, followers, followingtwitterReceive- Polling trigger for mentions, DMs, timeline
Telegram Nodes (2 nodes)
telegramSend- Dual-purpose: text, photo, document, location, contacttelegramReceive- Event-driven trigger via long-polling
Email Nodes (3 nodes)
IMAP/SMTP integration via the Himalaya CLI. Supports Gmail, Outlook, Yahoo, iCloud, ProtonMail (Bridge), Fastmail, and custom/self-hosted servers. Credentials stored via auth_service.store_api_key() -- see email_service.md.
emailSend- Dual-purpose: send via SMTP (to, subject, body, cc, bcc, body_type text/html)emailRead- Dual-purpose: list / search / read / folders / move / delete / flag via IMAPemailReceive- Polling trigger with baseline detection (poll_interval 30-3600s)
Social Nodes (2 nodes)
Unified multi-platform messaging (WhatsApp, Telegram, Discord, Slack, SMS, Email, Matrix, Teams):
socialReceive- Normalize messages from platform triggerssocialSend- Dual-purpose unified send
Android Nodes (16 nodes)
Android device connection is now configured via the Credentials modal (Android panel), not a workflow node. Service nodes can be connected directly to any agent's
input-toolshandle.
System Monitoring (4 nodes)
batteryMonitor- Battery status, level, charging, temperaturenetworkMonitor- Network connectivity and typesystemInfo- Device/OS info, memory, hardwarelocation- GPS tracking with accuracy
App Management (2 nodes)
appLauncher- Launch applications by package nameappList- List installed applications
Device Automation (6 nodes)
wifiAutomation- WiFi enable/disable, scan, statusbluetoothAutomation- Bluetooth enable/disable, paired devicesaudioAutomation- Volume control, mute/unmutedeviceStateAutomation- Airplane mode, screen, power save, brightnessscreenControlAutomation- Brightness, wake, timeoutairplaneModeControl- Airplane mode status and control
Sensors (2 nodes)
motionDetection- Accelerometer, gyroscope, shake detectionenvironmentalSensors- Temperature, humidity, pressure, light
Media (2 nodes)
cameraControl- Camera info, take photosmediaControl- Media playback, volume
Utility Nodes (5 nodes)
httpRequest- HTTP requests (GET, POST, PUT, DELETE, PATCH) with optional proxy support (useProxy: true)webhookResponse- Custom response to webhook callerconsole- Debug logging outputteamMonitor- Real-time monitoring of Agent Team operationsprocessManager- Start/stop/manage long-running processes
Proxy Nodes (3 nodes)
proxyRequest- HTTP requests through residential proxy providers with geo-targeting and failoverproxyConfig- Dual-purpose: configure providers, credentials, routing rulesproxyStatus- View proxy provider health, scores, and usage statistics
Code Nodes (4 nodes)
All dual-purpose (workflow node + AI tool):
pythonExecutor- Python code execution (in-process)javascriptExecutor- JavaScript execution via the persistent JS executor sidecar (Express on bun;server/nodejs/)typescriptExecutor- TypeScript execution via the same sidecar (bun transpiles TypeScript natively; no tsx)montyExecutor- Sandboxed Python via the Monty interpreter
Chat Nodes (2 nodes)
chatSend- Send via JSON-RPC 2.0 WebSocketchatHistory- Retrieve chat message history
Document Processing Nodes (6 nodes)
RAG pipeline nodes for document ingestion, processing, and vector storage:
httpScraper- Scrape links from web pages (date/page pagination modes)fileDownloader- Parallel file downloads with semaphore concurrencydocumentParser- Parse documents to text (PyPDF, Marker OCR, Unstructured, BeautifulSoup)textChunker- Split text into overlapping chunks (recursive, markdown, token strategies)embeddingGenerator- Generate vector embeddings (HuggingFace, OpenAI, Ollama providers)vectorStore- Store/query vectors (ChromaDB, Qdrant, Pinecone backends)
Web Scraping Nodes (2 nodes)
apifyActor- Dual-purpose: run Apify pre-built actors (Instagram, TikTok, Twitter, LinkedIn, Google Search, Maps, etc.)crawleeScraper- Crawlee web scraping with static and Playwright modes
Example Workflow JSON
Basic Workflow (Start -> AI Agent)
{
"id": "1234567890",
"name": "AI Agent with Start Node",
"version": "1.0.0",
"createdAt": "2025-01-06T12:00:00.000Z",
"lastModified": "2025-01-06T12:30:00.000Z",
"nodes": [
{
"id": "start-1",
"type": "start",
"position": { "x": 100, "y": 100 },
"data": {
"label": "Start",
"initialData": "{\"message\": \"Hello World\", \"value\": 123}"
}
},
{
"id": "aiAgent-1",
"type": "aiAgent",
"position": { "x": 400, "y": 100 },
"data": {
"label": "AI Agent",
"provider": "anthropic",
"model": "claude-haiku-4-5-20251001",
"prompt": "{{start.message}}",
"systemMessage": "You are a helpful assistant"
}
}
],
"edges": [
{
"id": "edge-1",
"source": "start-1",
"target": "aiAgent-1",
"sourceHandle": "output-main",
"targetHandle": "input-main"
}
]
}
Workflow with Memory (Conversational AI)
{
"id": "1234567891",
"name": "AI Agent with Memory",
"version": "1.0.0",
"createdAt": "2025-01-06T12:00:00.000Z",
"lastModified": "2025-01-06T12:30:00.000Z",
"nodes": [
{
"id": "start-1",
"type": "start",
"position": { "x": 100, "y": 100 },
"data": {
"label": "Start",
"initialData": "{\"chatInput\": \"What did we discuss earlier?\"}"
}
},
{
"id": "simpleMemory-1",
"type": "simpleMemory",
"position": { "x": 400, "y": 250 },
"data": {
"label": "Memory",
"sessionId": "user-session-123",
"memoryType": "window",
"windowSize": 20
}
},
{
"id": "aiAgent-1",
"type": "aiAgent",
"position": { "x": 400, "y": 100 },
"data": {
"label": "AI Agent",
"provider": "anthropic",
"model": "claude-haiku-4-5-20251001",
"prompt": "{{start.chatInput}}",
"systemMessage": "You are a helpful assistant with memory of our conversation"
}
}
],
"edges": [
{
"id": "edge-main",
"source": "start-1",
"target": "aiAgent-1",
"sourceHandle": "output-main",
"targetHandle": "input-main"
},
{
"id": "edge-memory",
"source": "simpleMemory-1",
"target": "aiAgent-1",
"sourceHandle": "output-tool",
"targetHandle": "input-tools"
}
]
}
Memory Workflow Behavior:
- Start node provides the user's chat input
- Simple Memory connects to AI Agent's
input-toolshandle via itsoutput-toolhandle (config connection) - When AI Agent runs, it loads conversation history from the memory session
- AI Agent's response is automatically saved to the memory session
- Simple Memory node can see Start node's outputs (via AI Agent) for parameter mapping
Usage Examples
Export Workflow
import { useAppStore } from './store/useAppStore';
// Export to JSON string
const workflow = useAppStore.getState().currentWorkflow;
const jsonString = useAppStore.getState().exportWorkflowToJSON();
console.log(jsonString);
// Export to file download
useAppStore.getState().exportWorkflowToFile();
Import Workflow
import { useAppStore } from './store/useAppStore';
// Import from JSON string
const jsonString = '{ ... }';
useAppStore.getState().importWorkflowFromJSON(jsonString);
// Import from file
import { importWorkflowFromFile } from './utils/workflowExport';
const fileInput = document.createElement('input');
fileInput.type = 'file';
fileInput.accept = '.json';
fileInput.onchange = async (e) => {
const file = (e.target as HTMLInputElement).files?.[0];
if (file) {
const workflow = await importWorkflowFromFile(file);
useAppStore.getState().setCurrentWorkflow(workflow);
}
};
fileInput.click();
Validate Workflow
import { validateWorkflow } from './schemas/workflowSchema';
const workflow = {
id: '123',
name: 'My Workflow',
nodes: [...],
edges: [...],
createdAt: new Date().toISOString(),
lastModified: new Date().toISOString()
};
const validation = validateWorkflow(workflow);
if (validation.valid) {
console.log('Workflow is valid');
} else {
console.error('Validation errors:', validation.errors);
}
Config Node Architecture
Config nodes (memory, tools) are auxiliary nodes that connect to parent nodes via special handles instead of the main data flow.
Characteristics of Config Nodes
| Property | Config Node | Standard Node |
|---|---|---|
| Group | Contains 'memory' or 'tool' | Other groups |
| Input Handle | None (passive) | input-main |
| Output Handle | output-tool (simpleMemory), output-context (context node), output-model |
output-main |
| Target Handle | Parent's input-context, input-tools, input-skill, input-teammates (input-memory is retired: the validator rejects it, the migration rewrites it) |
Parent's input-main |
| Parent Visibility | NOT shown in parent's input panel | Shown in parent's input panel |
| Input Inheritance | Inherits parent's main inputs | Only direct connections |
Config Node Detection
Nodes are identified as config nodes by the backend-derived isConfigNode uiHint:
const isConfigNode = (nodeType: string): boolean => {
const definition = resolveNodeDescription(nodeType);
return definition?.uiHints?.isConfigNode === true;
};
The backend derives the flag from the plugin's group tuple via
_CONFIG_NODE_GROUPS = frozenset({"memory", "tool"}) in
services/plugin/base.py; the frontend never re-derives it from group strings.
Input Inheritance for Config Nodes
When a config node is connected to a parent's config handle:
- The parent node does NOT see the config node as an input
- The config node DOES see the parent's main inputs (labeled "via Parent")
This allows memory nodes to access the same input data as the AI Agent they're connected to, enabling template variable mapping like {{start.chatInput}} in the memory node's session ID.
┌─────────────┐ main ┌─────────────┐
│ Start │──────────────▶│ AI Agent │
└─────────────┘ └─────────────┘
▲
│ input-memory
┌─────────────┐
│ Memory │
│ (sees Start │
│ via Agent) │
└─────────────┘
Node Data Structure
Each node contains:
id: Unique identifier (string)type: Node type (see supported types)position: { x: number, y: number }data: Node-specific parameters (object)label: Display label- Additional parameters based on node type
Start Node Data
{
"initialData": "{\"key1\": \"value1\", \"key2\": 123}"
}
AI Agent Node Data
{
"provider": "anthropic" | "openai" | "gemini" | "openrouter",
"model": "model-name",
"apiKey": "api-key-string",
"prompt": "{{start.message}}",
"systemMessage": "System instructions",
"temperature": 0.7,
"maxTokens": 1000
}
OpenRouter Chat Model Node Data
{
"model": "openai/gpt-4o-mini",
"prompt": "{{start.message}}",
"options": {
"systemMessage": "You are a helpful assistant",
"temperature": 0.7,
"maxTokens": 1000,
"topP": 1,
"frequencyPenalty": 0,
"presencePenalty": 0,
"timeout": 60000,
"maxRetries": 2
}
}
OpenRouter model IDs use the format provider/model-name:
openai/gpt-4o,openai/gpt-4o-minianthropic/claude-3.5-sonnet,anthropic/claude-3-haikugoogle/gemini-pro,google/gemini-flash-1.5meta-llama/llama-3.1-70b-instruct- Free models are prefixed with
[FREE]in the dropdown
Simple Memory Node Data
{
"sessionId": "conversation-session-id",
"memoryType": "buffer" | "window",
"windowSize": 10
}
Memory nodes are config nodes that:
- Connect to AI Agent via the
input-toolshandle (output-tool->input-tools); conversation continuity lives on the context node'soutput-context->input-contextedge - Store durable facts the agent explicitly remembers (persisted across restarts)
- Support buffer mode (all messages) or window mode (last N messages)
- Inherit parent node's main inputs for parameter mapping
Trigger Node Data (WhatsApp Trigger)
{
"messageTypeFilter": "all" | "text" | "image" | "video" | "audio",
"filter": "all" | "contact" | "group" | "keywords",
"contactPhone": "+1234567890",
"groupId": "group-id",
"keywords": "word1, word2",
"ignoreOwnMessages": true,
"includeMediaData": false
}
Trigger nodes:
- Wait for external events using asyncio.Future
- Have no main input (they start workflows)
- Output event data when triggered
Edge Data Structure
Each edge contains:
id: Unique identifiersource: Source node IDtarget: Target node IDsourceHandle: Output handle ID (default: "output-main")targetHandle: Input handle ID (default: "input-main")type: Rendering type ("default", "straight", "step", etc.)
Handle Naming Conventions
Main Data Flow Handles
output-main/input-main- Primary data flow between nodes
Config Handles (for auxiliary nodes)
Config handles connect memory/tool nodes to parent nodes without being part of main data flow:
input-context- Context node input (AI Agent; conversation continuity)input-tools- Tools configuration input (AI Agent; includessimpleMemory)input-skill- Skill configuration input (AI Agent)input-teammates- Teammate agents input (team lead)input-memory- retired; the validator rejects it andnormalize_workflow_graphrewrites legacy edgesinput-model- Model configuration inputoutput-model- Model/config output (circular nodes)output-tool- Tool output (simpleMemory node)output-context- Context output (context node)
Handle Detection Pattern
Config handles follow the pattern input-<type>, excluding the four data-flow handles
(client/src/components/parameterPanel/InputSection.tsx:259-265):
const isConfigHandle = (handle: string | null | undefined): boolean => {
if (!handle) return false;
if (handle.startsWith('input-') && handle !== 'input-main' && handle !== 'input-chat' && handle !== 'input-task' && handle !== 'input-teammates') {
return true;
}
return false;
};
Config Node Connection Example
{
"edges": [
{
"id": "edge-memory",
"source": "simpleMemory-1",
"target": "aiAgent-1",
"sourceHandle": "output-tool",
"targetHandle": "input-tools"
},
{
"id": "edge-main",
"source": "start-1",
"target": "aiAgent-1",
"sourceHandle": "output-main",
"targetHandle": "input-main"
}
]
}
In this example:
- The simpleMemory node connects to AI Agent's
input-toolshandle viaoutput-tool(config connection) - The start node connects to AI Agent's
input-mainhandle (main data flow) - AI Agent does NOT see simpleMemory as an input (config handles are filtered)
- simpleMemory DOES see Start node's outputs (inherits parent's main inputs)
Dynamic Parameter Resolution
Template variables in node parameters are resolved using the format {{nodeName.property}}:
{
"prompt": "{{start.message}}"
}
This resolves to the message property from the Start node's output data.
Validation Rules
- Workflow must have required fields: id, name, slug, nodes, edges, createdAt, lastModified
- New workflow IDs must be positive decimal strings (
^[1-9][0-9]*$) allocated by the backend — stable for the workflow lifetime and never changed on rename. Pre-cutover records retain their stored IDs. - Workflow slug must be
<Sanitized_Name>_<N>(^[A-Za-z0-9]+(_[0-9]+)?$) — derived fromnameviaservices.workflow_naming.next_available_slug; unique across active workflows; mutable on rename - Each node must have
id,type, andposition; canonical node IDs are<workflow_id>:<plugin_type>:<ordinal>, where plugin type comes from fixed plugin metadata and the ordinal permits repeated instances - Each edge must have: id, source, target
- Edge source and target must reference existing nodes
- Node types must be one of the supported types
Version History
1.4.0 (2026-01-27): Comprehensive node type expansion to 58 nodes
- Added Groq and Cerebras AI chat model nodes (6 total AI models)
- Added 9 AI Skill nodes for Chat Agent (claude, whatsapp, memory, maps, http, scheduler, android, code, custom)
- Added 4 AI Tool nodes for AI Agent (calculator, currentTime, webSearch, androidTool)
- Added whatsappChatHistory node (4 WhatsApp nodes total)
- Added scheduler nodes: timer, cronScheduler (with timezone support)
- Added chat nodes: chatSend, chatHistory (JSON-RPC 2.0 WebSocket)
- Added utility nodes: chatTrigger, console (5 utility nodes total)
- Added javascriptExecutor code node (2 code nodes total)
1.3.0 (2026-01-19): OpenRouter AI provider integration
- Added openrouterChatModel to AI Nodes list
- Added OpenRouter node data structure with model ID format
- Updated AI Agent provider options to include openrouter
1.2.0 (2025-12-19): Config node architecture and expanded node types
- Added Config Node Architecture section with input inheritance
- Added 31 supported node types (AI, Android, WhatsApp, Location, Code)
- Added handle naming conventions (main vs config handles)
- Added Simple Memory and Trigger node data structures
- Added workflow with memory example
- Updated edge documentation with config handle patterns
1.1.0 (2025-01-10): Android and WhatsApp integration
- Added 17 Android service nodes
- Added WhatsApp messaging nodes
- Added trigger node support
1.0.0 (2025-01-06): Initial schema definition
- Basic workflow structure
- Node and edge definitions
- Validation rules
- Export/import functionality