Workflow API

Workflow API

Overview

The Workflow API provides endpoints for managing workflow state, checkpoints, and execution control. Use these endpoints to inspect workflow progress, debug execution, and control running workflows.

Endpoints

Get Workflow State

GET /api/v1/workflow/state/{thread_id}

Get the complete workflow state for a given thread_id. Retrieves the latest checkpoint state from the checkpointer.

Path Parameters

Response 200 OK

{
  "thread_id": "abc-123",
  "checkpoint_id": "1ef663ba-28fe-6528-8002-5a559208592c",
  "messages": [
    {"role": "human", "content": "Write a script"},
    {"role": "ai", "content": "I'll help you write..."}
  ],
  "plan": null,
  "observations": [],
  "final_report": null,
  "research_topic": null,
  "market_type": null,
  "locale": "en-US",
  "deepthinking": false,
  "auto_accepted_plan": true,
  "plan_iterations": 0,
  "completed": true,
  "next_nodes": [],
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}

Errors

Example

curl "http://localhost:8000/api/v1/workflow/state/abc-123"

Get Checkpoint History

GET /api/v1/workflow/{thread_id}/checkpoints

Get checkpoint history for a workflow thread. Returns chronologically ordered list (newest first).

Path Parameters

Query Parameters

Response 200 OK

{
  "thread_id": "abc-123",
  "total_checkpoints": 4,
  "checkpoints": [
    {
      "checkpoint_id": "1ef663ba-28fe-6528-8002-5a559208592c",
      "parent_checkpoint_id": "1ef663ba-28f9-6ec4-8001-31981c2c39f8",
      "created_at": "2025-01-15T10:35:00Z",
      "metadata": {
        "source": "loop",
        "step": 2,
        "writes": {"agent": {"messages": [...]}}
      },
      "next_nodes": [],
      "pending_tasks": 0,
      "tasks": [],
      "completed": true,
      "state_preview": {
        "research_topic": null,
        "plan_iterations": 0,
        "has_final_report": false,
        "message_count": 5,
        "deepthinking": false
      }
    }
  ]
}

Use Cases:

• Time-travel debugging: Inspect state at different execution points
• State inspection: Understand workflow progression
• Debugging: Identify where interrupts or errors occurred

Errors

Example

curl "http://localhost:8000/api/v1/workflow/abc-123/checkpoints?limit=5"

Cancel Workflow

POST /api/v1/workflow/{thread_id}/cancel

Explicitly cancel a workflow execution. Sets cancellation flag that the streaming generator will check.

Path Parameters

Response 200 OK

{
  "cancelled": true,
  "thread_id": "abc-123",
  "message": "Cancellation signal sent. Workflow will stop shortly."
}

Example

curl -X POST "http://localhost:8000/api/v1/workflow/abc-123/cancel"

Soft Interrupt Workflow

POST /api/v1/workflow/{thread_id}/soft-interrupt

Soft interrupt a workflow - pause main agent while keeping subagents running.

Unlike /cancel which stops everything, soft interrupt:

• Signals the main agent to pause at the next safe point
• Background subagents continue execution
• Workflow can be resumed with new input

This is designed for the CLI ESC key behavior where the user wants to interrupt the current response but keep background work running.

Path Parameters

Response 200 OK

{
  "status": "soft_interrupted",
  "thread_id": "abc-123",
  "can_resume": true,
  "background_tasks": ["researcher", "analyst"]
}

Example

curl -X POST "http://localhost:8000/api/v1/workflow/abc-123/soft-interrupt"

Get Workflow Status

GET /api/v1/workflow/{thread_id}/status

Get current workflow execution status. Checks Redis for active/disconnected/completed status and combines with checkpoint data.

Path Parameters

Response 200 OK

{
  "thread_id": "abc-123",
  "status": "disconnected",
  "can_reconnect": true,
  "last_update": "2025-01-15T10:35:00Z",
  "workspace_id": "ws-456",
  "user_id": "user-789",
  "progress": {
    "has_plan": false,
    "has_final_report": false,
    "message_count": 15,
    "completed": false,
    "checkpoint_id": "ckpt-abc"
  },
  "active_subagents": ["researcher"],
  "completed_subagents": ["analyst"],
  "soft_interrupted": false
}

Status Values:

Example

curl "http://localhost:8000/api/v1/workflow/abc-123/status"

Resume Workflow (Deprecated)

POST /api/v1/workflow/{thread_id}/resume

DEPRECATED: Use the chat endpoint with hitl_response parameter instead.

# Instead of this deprecated endpoint, use:
curl -X POST "http://localhost:8000/api/v1/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws-abc123",
    "thread_id": "abc-123",
    "hitl_response": {"interrupt-1": {"decisions": [{"type": "approve"}]}},
    "messages": [{"role": "user", "content": "Continue"}]
  }'

Response 410 GONE

{
  "message": "This endpoint is deprecated. Use POST /api/v1/chat/stream with hitl_response instead.",
  "migration": {
    "endpoint": "POST /api/v1/chat/stream",
    "example": {
      "workspace_id": "ws-abc123",
      "thread_id": "abc-123",
      "hitl_response": {"interrupt-1": {"decisions": [{"type": "approve"}]}},
      "messages": [{"role": "user", "content": "Continue"}]
    }
  }
}