AI Workflow Execution

AI Workflow execution APIs run a published or testable workflow graph with explicit payload and context data, then return the execution state created by the runtime.

Key concepts

Term	Definition
Workflow ID	Identifier of the AI Workflow or workflow version to execute, depending on the integration contract.
Execution ID	Identifier returned by a started execution and used when resuming a paused or waiting flow.
Payload	The event data that enters the workflow.
Context	Runtime metadata such as channel, user, interaction, tenant, or space values.
Resume event	Data supplied when a waiting execution should continue.

What you can do

Action	Endpoint
Execute a workflow	POST /llm-chain/aiworkflow/:id/execute
Resume an execution	POST /llm-chain/aiworkflow/execution/:executionId/resume
Load the sample graph	GET /llm-chain/graph/sample

Execute a workflow

Use this route from trusted server-side code when an external system needs to start a Octo workflow.

curl -X POST "$OCTO_BASE_URL/llm-chain/aiworkflow/workflow_123/execute" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": { "message": "I need help with my order" },
    "context": { "channel": "web", "spaceId": "space_123" }
  }'

The request body is organized around payload and context objects. Keep customer-provided content in payload; keep operational metadata in context so the runtime can route logs, interactions, and tool calls consistently.

Resume a workflow execution

A workflow can pause at a wait node, human handoff, external callback, or another runtime state that needs a later event. Resume it with the execution ID returned by the original execution.

curl -X POST "$OCTO_BASE_URL/llm-chain/aiworkflow/execution/execution_123/resume" \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": { "message": "Here is the confirmation code" }
  }'

Runtime expectations

1. The controller starts a transaction for execution changes.
2. The runtime loads the graph, nodes, edges, and workflow configuration.
3. Nodes execute in graph order until an end node, wait state, transfer, or failure is reached.
4. Execution state and logs are returned to the caller and surfaced in product debugging views when linked to an interaction.

Error handling

Situation	What to check
Workflow not found	Confirm the workflow ID, active space, and access permissions.
No published version	Publish the workflow before routing production entry points or external integrations to it.
Execution waiting	Resume with the execution ID and the next event payload.
Tool failure	Test the tool directly from Developer > Tools or the Tools UI.
Runtime exception	Inspect the interaction execution path and workflow version configuration.

FAQ

Should I call the workflow or the entry point? Use an entry point for normal channel traffic. Use this API when a trusted integration needs direct execution behavior.

Can I resume any execution? Only resume executions that are in a waiting or resumable state and that belong to the same tenant and space context as your integration.

Related pages

• Runtime Guide - graph structure, node execution, wait, and resume behavior
• Interactions - create and finalize conversation records around executions
• AI Workflows - build and publish workflow versions