Skip to main content

​
What is a Start Node?

The Start Node is the entry point of every workflow. When a workflow is triggered — via chat, API, or an external event — execution begins at the specified Start node, which passes the incoming payload to downstream nodes. Every workflow must have at least one Start node. A workflow can have multiple Start nodes to support different entry points for different use cases.
Start node visual representation
Start node visual representation

​
How It Works

The Start node is simple — it receives the raw input payload and passes it through as its output. Downstream nodes access the payload fields via variable mappings like {{ start.text }}, {{ start.chat_id }}, {{ start.files }}, etc. The payload structure depends on how the workflow is triggered:
When triggered via the chat interface or POST /v1/workflow-requests/run:
{
  "text": "User's message or query",
  "chat_id": "uuid-of-the-chat-session",
  "files": [
    { "url": "https://...", "name": "document.pdf", "type": "application/pdf" }
  ]
}
FieldDescription
textThe user’s message or query
chat_idUUID of the chat session (used by Agent nodes for context memory)
filesOptional array of uploaded files

​
Configuration

Description: A name to identify this Start node on the canvas and in the start node selector.Type: StringRequired: YesExample:
"Chat Handler"
"Event Processor"  
"API Endpoint"
Use descriptive labels — when a workflow has multiple Start nodes, users and API callers need to choose which one to trigger.
Description: Reference data from other nodes using Jinja2 templates.Type: Variable mapping listRequired: NoSee Variable Mappings for details.
Description: Number of automatic retries on transient failures.Type: NumberDefault: 3Range: 0–10
Description: Maximum execution time in minutes.Type: NumberDefault: 525,600 (1 year)

​
Handles

HandlePositionTypeDescription
PARALLELRightExecutionSends the input payload to downstream nodes
ERRORRightErrorRoutes to fallback nodes if the start node fails
Start nodes have no input handle — they are always the first node in the execution chain.

​
How to Trigger Workflows

​
1. Chat Interface

The most common way to trigger a workflow during development and testing:
  1. Open a workflow in the editor
  2. Open the Chat panel
  3. Select a Start node from the dropdown
  4. Type a message and send
The message becomes {{ start.text }} and the chat session ID becomes {{ start.chat_id }}.

​
2. API — Run Workflow

Trigger a workflow programmatically via the API: 
POST https://app.splox.io/api/v1/workflow-requests/run
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "workflow_version_id": "your-workflow-version-id",
  "chat_id": "your-chat-id",
  "start_node_id": "your-start-node-id",
  "query": "Process this request",
  "files": []
}
Response: 
{
  "workflow_request_id": "uuid-of-the-execution"
}
Use the returned workflow_request_id to:
  • Listen for results: GET /v1/workflow-requests/{id}/listen (SSE stream)
  • Get execution tree: GET /v1/workflow-requests/{id}/execution-tree
  • Get history: GET /v1/workflow-requests/{id}/history
Rate limited to 20 workflow executions per minute per user.

​
Multiple Start Nodes

A single workflow can have multiple Start nodes for different entry points: 
Workflow: Customer Support
├── Start: "Chat Handler"       ← For interactive chat sessions
├── Start: "Internal Agent"     ← For agent-to-agent calls
└── Start: "API Requests"       ← For programmatic API calls
When triggering a workflow, you specify which Start node to use via the start_node_id parameter. In the chat interface, a dropdown lets you select the active Start node.
Use multiple Start nodes when your workflow needs to handle different types of input — each Start node can lead to a different processing path.

​
Best Practices

Descriptive Labels

Name Start nodes clearly — they appear in dropdowns and API calls

Handle Missing Fields

Use conditional logic (Switch nodes or template defaults) to handle cases where optional payload fields may be missing

One Concern Per Start

Create separate Start nodes for different trigger sources rather than handling everything in one

​
What’s Next?

Agent Node

Connect your Start node to an Agent to process the incoming data

Variable Mappings

Access Start node payload data in downstream nodes

Node Lifecycle

Understand execution states and transitions

Build Your First Agent

Step-by-step tutorial using a Start node