Execute Workflow

curl --request POST \
  --url https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "run_input": {
    "dynamic_variables": {},
    "runtime_variables": {},
    "miscellaneous": {},
    "command": "start",
    "workflow_id": "5eb7cf5a86d9755df3a6c593",
    "version_number": 0,
    "run_by": "<string>",
    "workflow_run_id": "5eb7cf5a86d9755df3a6c593",
    "team_id": "<string>",
    "start_node_logical_id": "<string>",
    "initial_state": {},
    "thread_to_node_inputs": {},
    "welcome_message": "<string>"
  },
  "run_id": "<string>"
}
'

import requests

url = "https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute"

payload = {
    "run_input": {
        "dynamic_variables": {},
        "runtime_variables": {},
        "miscellaneous": {},
        "command": "start",
        "workflow_id": "5eb7cf5a86d9755df3a6c593",
        "version_number": 0,
        "run_by": "<string>",
        "workflow_run_id": "5eb7cf5a86d9755df3a6c593",
        "team_id": "<string>",
        "start_node_logical_id": "<string>",
        "initial_state": {},
        "thread_to_node_inputs": {},
        "welcome_message": "<string>"
    },
    "run_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    run_input: {
      dynamic_variables: {},
      runtime_variables: {},
      miscellaneous: {},
      command: 'start',
      workflow_id: '5eb7cf5a86d9755df3a6c593',
      version_number: 0,
      run_by: '<string>',
      workflow_run_id: '5eb7cf5a86d9755df3a6c593',
      team_id: '<string>',
      start_node_logical_id: '<string>',
      initial_state: {},
      thread_to_node_inputs: {},
      welcome_message: '<string>'
    },
    run_id: '<string>'
  })
};

fetch('https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'run_input' => [
        'dynamic_variables' => [
                
        ],
        'runtime_variables' => [
                
        ],
        'miscellaneous' => [
                
        ],
        'command' => 'start',
        'workflow_id' => '5eb7cf5a86d9755df3a6c593',
        'version_number' => 0,
        'run_by' => '<string>',
        'workflow_run_id' => '5eb7cf5a86d9755df3a6c593',
        'team_id' => '<string>',
        'start_node_logical_id' => '<string>',
        'initial_state' => [
                
        ],
        'thread_to_node_inputs' => [
                
        ],
        'welcome_message' => '<string>'
    ],
    'run_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute"

	payload := strings.NewReader("{\n  \"run_input\": {\n    \"dynamic_variables\": {},\n    \"runtime_variables\": {},\n    \"miscellaneous\": {},\n    \"command\": \"start\",\n    \"workflow_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"version_number\": 0,\n    \"run_by\": \"<string>\",\n    \"workflow_run_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"team_id\": \"<string>\",\n    \"start_node_logical_id\": \"<string>\",\n    \"initial_state\": {},\n    \"thread_to_node_inputs\": {},\n    \"welcome_message\": \"<string>\"\n  },\n  \"run_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"run_input\": {\n    \"dynamic_variables\": {},\n    \"runtime_variables\": {},\n    \"miscellaneous\": {},\n    \"command\": \"start\",\n    \"workflow_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"version_number\": 0,\n    \"run_by\": \"<string>\",\n    \"workflow_run_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"team_id\": \"<string>\",\n    \"start_node_logical_id\": \"<string>\",\n    \"initial_state\": {},\n    \"thread_to_node_inputs\": {},\n    \"welcome_message\": \"<string>\"\n  },\n  \"run_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"run_input\": {\n    \"dynamic_variables\": {},\n    \"runtime_variables\": {},\n    \"miscellaneous\": {},\n    \"command\": \"start\",\n    \"workflow_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"version_number\": 0,\n    \"run_by\": \"<string>\",\n    \"workflow_run_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"team_id\": \"<string>\",\n    \"start_node_logical_id\": \"<string>\",\n    \"initial_state\": {},\n    \"thread_to_node_inputs\": {},\n    \"welcome_message\": \"<string>\"\n  },\n  \"run_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "run_id": "<string>",
  "status": "not_started",
  "turn_number": 123,
  "events": [
    {}
  ],
  "is_waiting_for_input": true,
  "is_completed": true,
  "error": "<string>",
  "next_input_hint": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Workflow Execution

Execute Workflow

Execute a workflow interactively over standard HTTP POST.

First turn (run_id absent in request body): Starts a new interactive session, runs until pause/terminal, and returns a run_id the client must echo back on all subsequent requests.

Subsequent turns (run_id present): Resumes the paused session with new user input, runs until the next pause or terminal state.

Cancellation (run_id present, run_input.command = "stop"): Cancels the session, flushes state to MongoDB, returns status=CANCELLED.

POST

workflows

{workflow_id}

execute

Execute Workflow

curl --request POST \
  --url https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "run_input": {
    "dynamic_variables": {},
    "runtime_variables": {},
    "miscellaneous": {},
    "command": "start",
    "workflow_id": "5eb7cf5a86d9755df3a6c593",
    "version_number": 0,
    "run_by": "<string>",
    "workflow_run_id": "5eb7cf5a86d9755df3a6c593",
    "team_id": "<string>",
    "start_node_logical_id": "<string>",
    "initial_state": {},
    "thread_to_node_inputs": {},
    "welcome_message": "<string>"
  },
  "run_id": "<string>"
}
'

import requests

url = "https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute"

payload = {
    "run_input": {
        "dynamic_variables": {},
        "runtime_variables": {},
        "miscellaneous": {},
        "command": "start",
        "workflow_id": "5eb7cf5a86d9755df3a6c593",
        "version_number": 0,
        "run_by": "<string>",
        "workflow_run_id": "5eb7cf5a86d9755df3a6c593",
        "team_id": "<string>",
        "start_node_logical_id": "<string>",
        "initial_state": {},
        "thread_to_node_inputs": {},
        "welcome_message": "<string>"
    },
    "run_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    run_input: {
      dynamic_variables: {},
      runtime_variables: {},
      miscellaneous: {},
      command: 'start',
      workflow_id: '5eb7cf5a86d9755df3a6c593',
      version_number: 0,
      run_by: '<string>',
      workflow_run_id: '5eb7cf5a86d9755df3a6c593',
      team_id: '<string>',
      start_node_logical_id: '<string>',
      initial_state: {},
      thread_to_node_inputs: {},
      welcome_message: '<string>'
    },
    run_id: '<string>'
  })
};

fetch('https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'run_input' => [
        'dynamic_variables' => [
                
        ],
        'runtime_variables' => [
                
        ],
        'miscellaneous' => [
                
        ],
        'command' => 'start',
        'workflow_id' => '5eb7cf5a86d9755df3a6c593',
        'version_number' => 0,
        'run_by' => '<string>',
        'workflow_run_id' => '5eb7cf5a86d9755df3a6c593',
        'team_id' => '<string>',
        'start_node_logical_id' => '<string>',
        'initial_state' => [
                
        ],
        'thread_to_node_inputs' => [
                
        ],
        'welcome_message' => '<string>'
    ],
    'run_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute"

	payload := strings.NewReader("{\n  \"run_input\": {\n    \"dynamic_variables\": {},\n    \"runtime_variables\": {},\n    \"miscellaneous\": {},\n    \"command\": \"start\",\n    \"workflow_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"version_number\": 0,\n    \"run_by\": \"<string>\",\n    \"workflow_run_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"team_id\": \"<string>\",\n    \"start_node_logical_id\": \"<string>\",\n    \"initial_state\": {},\n    \"thread_to_node_inputs\": {},\n    \"welcome_message\": \"<string>\"\n  },\n  \"run_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"run_input\": {\n    \"dynamic_variables\": {},\n    \"runtime_variables\": {},\n    \"miscellaneous\": {},\n    \"command\": \"start\",\n    \"workflow_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"version_number\": 0,\n    \"run_by\": \"<string>\",\n    \"workflow_run_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"team_id\": \"<string>\",\n    \"start_node_logical_id\": \"<string>\",\n    \"initial_state\": {},\n    \"thread_to_node_inputs\": {},\n    \"welcome_message\": \"<string>\"\n  },\n  \"run_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-prod.interactly.ai/workflows/v1/workflows/{workflow_id}/execute")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"run_input\": {\n    \"dynamic_variables\": {},\n    \"runtime_variables\": {},\n    \"miscellaneous\": {},\n    \"command\": \"start\",\n    \"workflow_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"version_number\": 0,\n    \"run_by\": \"<string>\",\n    \"workflow_run_id\": \"5eb7cf5a86d9755df3a6c593\",\n    \"team_id\": \"<string>\",\n    \"start_node_logical_id\": \"<string>\",\n    \"initial_state\": {},\n    \"thread_to_node_inputs\": {},\n    \"welcome_message\": \"<string>\"\n  },\n  \"run_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "run_id": "<string>",
  "status": "not_started",
  "turn_number": 123,
  "events": [
    {}
  ],
  "is_waiting_for_input": true,
  "is_completed": true,
  "error": "<string>",
  "next_input_hint": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Retrieve your API Key from Dashboard API Keys Section.

Path Parameters

workflow_id

string

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

Query Parameters

version

integer | null

Workflow version to run. Applies to the first turn only; subsequent turns always use the version from the initial turn.

Required range: x >= 0

Body

application/json

Request body for POST /v1/workflows/{workflow_id}/execute.

Protocol

First turn — omit run_id. The server creates a WorkflowRunsModel in MongoDB, derives the run_id from its ObjectId, and returns it in the response.
Subsequent turns — echo back the run_id received in the previous response to continue the session.
Cancellation — echo back run_id and set run_input.command = "stop".

run_input

WorkflowRunInput · object

required

The workflow run input for this turn.

Show child attributes

run_id

string | null

Interactive session identifier. Omit on the first request — the server will derive one from MongoDB and return it. Echo back on all subsequent requests to continue the session.

Response

Successful Response

Response body for POST /v1/workflows/{workflow_id}/execute.

Returned for both first-turn (no run_id in request) and subsequent turns.

run_id

string

required

Session identifier (= MongoDB ObjectId of the underlying WorkflowRun record). Include in all subsequent POST requests to continue this session.

status

enum<string>

required

Status of the workflow run after this turn.

Available options:

not_started,

started,

running,

failed,

completed,

paused,

waiting_for_user_input,

cancelled,

aborted_looping_risk

turn_number

integer

required

The turn that this response corresponds to (1-indexed).

events

Events · object[]

required

All events emitted by the workflow runtime during this turn. Includes start/end-node events, LLM events, show-state events, and the terminal pause/end/error event.

is_waiting_for_input

boolean

required

True when the workflow paused and is waiting for user input in the next POST request.

is_completed

boolean

required

True when the workflow has reached a terminal state (completed, failed, cancelled, or aborted).

error

string | null

Present when status is FAILED. Human-readable error message.

next_input_hint

Next Input Hint · object | null

Serialised BusyWaitForUserMessageEvent payload when is_waiting_for_input=True. Describes what the workflow expects as input in the next turn.

Getting Started

APIs

Campaigns

Workflows

SMS

Execute Workflow

Authorizations

Path Parameters

Query Parameters

Body

Protocol

Response