Workflows API

The Workflows API allows you to list, execute, and monitor multi-step agent workflows programmatically.

Base URL

https://dreamsolve.ai/api/v1

Authentication

All endpoints require authentication via the x-api-key header. See the API Overview for details.

---

List Workflows

Retrieve all accessible workflows (system and user-owned).

GET /api/v1/workflows

Response

[
  {
    "id": "1",
    "name": "Product Analysis",
    "slug": "product-analysis",
    "description": "Chains product ideation, market analysis, and pitch creation.",
    "is_system": true,
    "config": {
      "category": "product",
      "tags": ["ideation", "market-analysis", "pitch"]
    },
    "steps": [
      {
        "id": "1",
        "step_order": 1,
        "agent_slug": "product-idea-generator",
        "name": "Generate Product Ideas"
      },
      {
        "id": "2",
        "step_order": 2,
        "agent_slug": "product-market-analysis",
        "name": "Analyze Market Fit"
      },
      {
        "id": "3",
        "step_order": 3,
        "agent_slug": "pitch-agent",
        "name": "Create Pitch"
      }
    ]
  }
]

---

Execute Workflow

Execute a workflow synchronously or asynchronously.

POST /api/v1/workflows/:workflowId/execute

Path Parameters

Parameter	Type	Description
workflowId	string	The workflow ID to execute

Request Body

{
  "input": "A mobile app for tracking personal fitness goals",
  "nodeId": "192",
  "async": true
}

Field	Type	Required	Description
input	string	Yes	Initial input text for the workflow
nodeId	string	No	Node to associate the execution with
conversationId	string	No	Existing conversation to continue
async	boolean	No	If true, returns immediately with an execution ID (default: false)

Response (async)

Status Code: 202 Accepted

{
  "executionId": "42",
  "workflowId": "1",
  "status": "pending"
}

Response (sync)

{
  "executionId": "42",
  "workflowId": "1",
  "status": "completed",
  "currentStep": 3,
  "totalSteps": 3,
  "finalOutput": "Here is the investor pitch...",
  "stepOutputs": [
    {
      "stepOrder": 1,
      "stepName": "Generate Product Ideas",
      "agentSlug": "product-idea-generator",
      "status": "completed",
      "output": "Product idea details..."
    },
    {
      "stepOrder": 2,
      "stepName": "Analyze Market Fit",
      "agentSlug": "product-market-analysis",
      "status": "completed",
      "output": "Market analysis..."
    },
    {
      "stepOrder": 3,
      "stepName": "Create Pitch",
      "agentSlug": "pitch-agent",
      "status": "completed",
      "output": "Investor pitch..."
    }
  ]
}

---

Get Execution Status

Check the status of a workflow execution, including step-level details.

GET /api/v1/workflows/executions/:executionId

Path Parameters

Parameter	Type	Description
executionId	string	The execution ID

Response

{
  "id": "42",
  "workflow_id": "1",
  "status": "running",
  "current_step": 2,
  "total_steps": 3,
  "initial_input": "A mobile app for tracking fitness goals",
  "started_at": "2025-01-15T10:00:00Z",
  "step_executions": [
    {
      "id": "101",
      "step_order": 1,
      "status": "completed",
      "output": "Product idea details...",
      "workflow_step": {
        "agent_slug": "product-idea-generator",
        "name": "Generate Product Ideas"
      },
      "agent_execution": {
        "id": "201",
        "conversation_id": "conv_abc",
        "status": "completed"
      }
    },
    {
      "id": "102",
      "step_order": 2,
      "status": "running",
      "workflow_step": {
        "agent_slug": "product-market-analysis",
        "name": "Analyze Market Fit"
      }
    }
  ]
}

Execution Status Values

Status	Description
pending	Execution created, not yet started
running	Workflow is actively executing steps
completed	All steps finished successfully
failed	A step failed, halting the workflow
cancelled	Execution was cancelled by the user

---

Cancel Execution

Cancel a running workflow execution.

DELETE /api/v1/workflows/executions/:executionId

Path Parameters

Parameter	Type	Description
executionId	string	The execution ID to cancel

Response

{
  "success": true
}

Only executions with status pending or running can be cancelled. Completed steps retain their results; remaining steps are marked as skipped.

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters or execution cannot be cancelled
401	Unauthorized - Invalid or missing API key
403	Forbidden - You do not own this execution
404	Not Found - Workflow or execution not found
500	Internal Server Error

---

Example Usage

Execute a workflow asynchronously

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "A mobile app for tracking personal fitness goals",
    "nodeId": "192",
    "async": true
  }' \
  https://dreamsolve.ai/api/v1/workflows/1/execute

Poll for completion

curl -H "x-api-key: YOUR_API_KEY" \
  https://dreamsolve.ai/api/v1/workflows/executions/42

Cancel a running workflow

curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  https://dreamsolve.ai/api/v1/workflows/executions/42