> ## Documentation Index
> Fetch the complete documentation index at: https://docs.splox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Workflow

> Triggers a workflow execution. Creates a workflow request with the given payload, enqueues it for processing, and returns a workflow_request_id for tracking.

Triggers a workflow execution. This is the primary way to run workflows programmatically.

## Usage

<CodeGroup>
  ```bash cURL theme={null}
  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",
      "entry_node_ids": ["your-entry-node-id"],
      "query": "Your message or instruction",
      "files": []
    }'
  ```

  ```python Python theme={null}
  from splox import SploxClient

  client = SploxClient(api_key="YOUR_API_KEY")
  result = client.workflows.run(
      workflow_version_id="your-workflow-version-id",
      chat_id="your-chat-id",
      entry_node_ids=["your-entry-node-id"],
      query="Your message or instruction",
  )
  print(result.workflow_request_id)

  # Or run and wait for completion:
  tree = client.workflows.run_and_wait(
      workflow_version_id="your-workflow-version-id",
      chat_id="your-chat-id",
      entry_node_ids=["your-entry-node-id"],
      query="Your message or instruction",
      timeout=300.0,
  )
  print(tree.execution_tree.status)
  ```

  ```typescript Node.js theme={null}
  import Splox from "splox";

  const client = new Splox("YOUR_API_KEY");
  const result = await client.workflows.run({
    workflow_version_id: "your-workflow-version-id",
    chat_id: "your-chat-id",
    entry_node_ids: ["your-entry-node-id"],
    query: "Your message or instruction",
  });
  console.log(result.workflow_request_id);

  // Or run and wait for completion:
  const tree = await client.workflows.runAndWait({
    workflow_version_id: "your-workflow-version-id",
    chat_id: "your-chat-id",
    entry_node_ids: ["your-entry-node-id"],
    query: "Your message or instruction",
  });
  console.log(tree.execution_tree.status);
  ```

  ```go Go theme={null}
  client := splox.NewClient("YOUR_API_KEY")
  result, err := client.Workflows.Run(ctx, splox.RunParams{
      WorkflowVersionID: "your-workflow-version-id",
      ChatID:            "your-chat-id",
      EntryNodeIDs:      []string{"your-entry-node-id"},
      Query:             "Your message or instruction",
  })
  fmt.Println(result.WorkflowRequestID)

  // Or run and wait for completion:
  tree, err := client.Workflows.RunAndWait(ctx, splox.RunParams{
      WorkflowVersionID: "your-workflow-version-id",
      ChatID:            "your-chat-id",
      EntryNodeIDs:      []string{"your-entry-node-id"},
      Query:             "Your message or instruction",
  }, 5*time.Minute)
  fmt.Println(tree.ExecutionTree.Status)
  ```
</CodeGroup>

## 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 entry node(s)
4. The entry 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](/api-reference/list-workflows) or [Get Latest Version](/api-reference/get-workflow-version)
2. **Entry node IDs** — Get them via [Get Entry Nodes](/api-reference/get-entry-nodes)
3. **A chat session** — Create one via [Create Chat](/api-reference/create-chat)

## Response

Returns a `workflow_request_id` you can use to:

* **Stream results in real-time:** [Listen to Execution (SSE)](/api-reference/listen-workflow-execution)
* **Get the full execution tree:** [Get Execution Tree](/api-reference/get-execution-tree)
* **View execution history:** [Get History](/api-reference/get-workflow-history)

## Rate Limit

**20 workflow executions per minute** per user.

## Notes

<Info>
  **Authentication required:** The authenticated user must own the workflow or have access via a published agent.
</Info>


## OpenAPI

````yaml POST /workflow-requests/run
openapi: 3.1.0
info:
  title: Splox API
  description: >-
    Run workflows, manage chats, receive events, and monitor execution via the
    Splox API
  version: 1.0.0
  contact:
    name: Splox Support
    email: support@splox.io
    url: https://community.splox.io
servers:
  - url: https://app.splox.io/api/v1
    description: Production API
security: []
tags:
  - name: MCP
    description: Discover MCP servers, manage connections, and execute MCP tools
  - name: Workflows
    description: List, get, and inspect workflows, versions, and nodes
  - name: Workflow Requests
    description: Run workflows, monitor execution, and retrieve results
  - name: Events
    description: Receive external events via Event Hub webhooks
  - name: Chats
    description: Manage chat sessions for workflow interactions
paths:
  /workflow-requests/run:
    post:
      tags:
        - Workflow Requests
      summary: Run Workflow
      description: >-
        Triggers a workflow execution. Creates a workflow request with the given
        payload, enqueues it for processing, and returns a workflow_request_id
        for tracking.
      operationId: runWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflow_version_id
                - chat_id
                - entry_node_ids
                - query
              properties:
                workflow_version_id:
                  type: string
                  format: uuid
                  description: ID of the workflow version to execute
                chat_id:
                  type: string
                  format: uuid
                  description: Chat session ID (used for context memory and SSE streaming)
                entry_node_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: IDs of the entry nodes to begin execution at
                query:
                  type: string
                  description: >-
                    The user message or query text. Available as {{ start.text
                    }} in the workflow.
                files:
                  type: array
                  description: >-
                    Optional file attachments. Available as {{ start.files }} in
                    the workflow.
                  items:
                    $ref: '#/components/schemas/WorkflowRequestFile'
                additional_params:
                  type: object
                  additionalProperties: true
                  description: Optional extra parameters merged into the payload
            example:
              workflow_version_id: 0199e001-a23b-7c8d-1234-567890abcdef
              chat_id: 0199f200-a11b-7c8d-4444-888890abcdef
              entry_node_ids:
                - 0199e002-b34c-8d9e-2345-678901bcdef0
              query: Summarize the latest sales report
              files: []
      responses:
        '200':
          description: Workflow execution started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflow_request_id:
                    type: string
                    format: uuid
                    description: >-
                      ID of the created workflow request. Use this to listen for
                      results, get the execution tree, or check status.
              example:
                workflow_request_id: 0199f123-d60e-7ffd-9131-4cc5ab040ee8
        '400':
          description: Bad request — invalid input or unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded (max 20 per minute per user)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    WorkflowRequestFile:
      type: object
      description: File attached to a workflow request
      properties:
        content_type:
          type: string
          description: MIME type of the file
        url:
          type: string
          format: uri
          description: URL to access the file
        file_name:
          type: string
          description: Original file name
        file_size:
          type: integer
          format: int64
          description: File size in bytes
        metadata:
          type: object
          additionalProperties: true
          description: Additional file metadata
      required:
        - url
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token generated from your Splox account settings. Create tokens at
        https://app.splox.io/account?tab=settings

````