Skip to main content
POST
/
workflow-requests
/
run
Run Workflow
curl --request POST \
  --url https://app.splox.io/api/v1/workflow-requests/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "workflow_version_id": "0199e001-a23b-7c8d-1234-567890abcdef",
  "chat_id": "0199f200-a11b-7c8d-4444-888890abcdef",
  "start_node_id": "0199e002-b34c-8d9e-2345-678901bcdef0",
  "query": "Summarize the latest sales report",
  "files": []
}
'
{
  "workflow_request_id": "0199f123-d60e-7ffd-9131-4cc5ab040ee8"
}
Triggers a workflow execution. This is the primary way to run workflows programmatically.

​
Usage

curl -X POST https://app.splox.io/api/v1/workflow-requests/run \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_version_id": "your-workflow-version-id",
    "chat_id": "your-chat-id",
    "start_node_id": "your-start-node-id",
    "query": "Your message or instruction",
    "files": []
  }'

​
How It Works

  1. The API creates a WorkflowRequest with status pending
  2. The request is enqueued for processing
  3. Execution begins at the specified Start node
  4. The Start node receives a payload: { "text": "<query>", "chat_id": "<chat_id>", "files": [...] }
  5. Downstream nodes access this via {{ start.text }}, {{ start.chat_id }}, etc.

​
Prerequisites

Before running a workflow, you need:
  1. A workflow version ID — Get it via List Workflows or Get Latest Version
  2. A start node ID — Get it via Get Start Nodes
  3. A chat session — Create one via Create Chat

​
Response

Returns a workflow_request_id you can use to:

​
Rate Limit

20 workflow executions per minute per user.

​
Notes

Authentication required: The authenticated user must own the workflow or have access via a published agent.

Authorizations

​
Authorization
string
header
required

API token generated from your Splox account settings. Create tokens at https://app.splox.io/account?tab=settings

Body

application/json
​
workflow_version_id
string<uuid>
required

ID of the workflow version to execute

​
chat_id
string<uuid>
required

Chat session ID (used for context memory and SSE streaming)

​
start_node_id
string<uuid>
required

ID of the Start node to begin execution at

​
query
string
required

The user message or query text. Available as {{ start.text }} in the workflow.

​
files
object[]

Optional file attachments. Available as {{ start.files }} in the workflow.

​
additional_params
object

Optional extra parameters merged into the payload

Response

Workflow execution started successfully

​
workflow_request_id
string<uuid>

ID of the created workflow request. Use this to listen for results, get the execution tree, or check status.