Skip to main content
POST
/
agentspec
/
flows
/
execute
Execute an Agent Spec flow
curl --request POST \
  --url http://localhost:5173/api/flowdrop/agentspec/flows/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow": {
    "component_type": "flow",
    "name": "document_processing",
    "start_node": "start",
    "nodes": [
      {
        "component_type": "start_node",
        "name": "process_input",
        "description": "<string>",
        "inputs": [
          {
            "title": "user_query",
            "type": "string",
            "description": "<string>",
            "default": "<unknown>",
            "enum": [
              "<unknown>"
            ],
            "items": "<unknown>",
            "properties": {},
            "required": [
              "<string>"
            ]
          }
        ],
        "outputs": [
          {
            "title": "user_query",
            "type": "string",
            "description": "<string>",
            "default": "<unknown>",
            "enum": [
              "<unknown>"
            ],
            "items": "<unknown>",
            "properties": {},
            "required": [
              "<string>"
            ]
          }
        ],
        "metadata": {}
      }
    ],
    "control_flow_connections": [
      {
        "name": "start_to_process",
        "from_node": "start",
        "to_node": "process_input",
        "from_branch": "high_priority"
      }
    ],
    "description": "<string>",
    "data_flow_connections": [
      {
        "name": "query_to_llm",
        "source_node": "process_input",
        "source_output": "processed_text",
        "destination_node": "llm_generate",
        "destination_input": "prompt"
      }
    ],
    "metadata": {}
  },
  "inputs": {
    "user_query": "What is the weather today?"
  }
}
'
{
  "execution_id": "exec-abc-123",
  "id": "<string>"
}

Authorizations

​
Authorization
string
header
required

JWT token for authentication

Body

application/json

Request to execute an Agent Spec flow on a runtime

​
flow
object
required

Agent Spec Flow — a directed, potentially cyclic graph of nodes. Flows function as "subroutines" encapsulating repeatable processes. They separate control-flow (execution order) from data-flow (data routing).

​
inputs
object

Initial input values for the flow

Example:
{
  "user_query": "What is the weather today?"
}

Response

Flow execution started successfully

Response after starting an Agent Spec execution

​
execution_id
string
required

Unique execution ID from the runtime

Example:

"exec-abc-123"

​
id
string

Alternative execution ID field

​
status
enum<string>

Initial execution status

Available options:
running,
completed,
failed,
cancelled