Workflows

Start workflow execution

Start a new execution of a workflow asynchronously. The workflow will begin processing in the background.

You’ll receive a 202 Accepted response with a tracking_id immediately. Use this tracking_id to:

Poll GET /workflow_executions with tracking_id filter to check status
Correlate execution events with your own systems

The execution will fail if:

The workflow is not in ‘active’ status
Required phone_number is missing or invalid
The workflow definition is malformed

Use cases:

Start workflow from external trigger (API, webhook, scheduled job)
Test workflow with specific initial variables
Retry failed execution with same parameters

Burst rate limit: This endpoint has an additional per-workflow burst limiter on top of the general platform API rate limits. The burst counter is scoped by API key and workflow ID and resets every second.

legacy / free: 5 requests per second
pro: 15 requests per second
enterprise / platform: 30 requests per second

Successful responses include X-Burst-RateLimit-Limit and X-Burst-RateLimit-Remaining headers. If the burst limit is exceeded, the API returns 429 Too Many Requests with Retry-After: 1.

POST

workflows

{workflow_id}

executions

Start workflow execution

curl --request POST \
  --url https://api.kapso.ai/platform/v1/workflows/{workflow_id}/executions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow_execution": {
    "phone_number": "+14155552671",
    "phone_number_id": "<string>",
    "whatsapp_config_id": 123,
    "variables": {
      "user_name": "Alice",
      "order_id": "ORD-12345",
      "priority": "high"
    },
    "context": {
      "source": "mobile_app",
      "campaign_id": "SUMMER2024"
    },
    "initial_data": {}
  }
}
'

{
  "data": {
    "message": "Workflow execution initiated",
    "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

workflow_id

string<uuid>

required

Workflow identifier

Body

application/json

Request to start a new workflow execution. Executions are processed asynchronously - you'll receive a tracking_id immediately and can poll for results using GET /workflow_executions/{id}.

workflow_execution

object

required

Show child attributes

Response

Workflow execution queued successfully (processing in background)

Async workflow execution initiation response (HTTP 202)

data

object

required

Async response returned when workflow execution is successfully queued (HTTP 202 Accepted). The execution will begin processing in the background. Use the id to retrieve execution details or the tracking_id to monitor progress.

Show child attributes

Retrieve workflow executionGet complete details for a workflow execution including current status, execution context, variables, and full event history. **This is the only endpoint that returns the full execution_context** (vars, system, context, metadata) along with the complete event history. Use this endpoint to: - Monitor execution progress and current step - Debug failed executions with full event log - Review execution variables and context - Check error details when status is 'failed' The response includes: - Current status and step - Complete event chronology (step transitions, agent actions, variable updates) - Full execution_context with standard structure (vars, system, context, metadata) - Error details if execution failed

Start workflow execution

curl --request POST \
  --url https://api.kapso.ai/platform/v1/workflows/{workflow_id}/executions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow_execution": {
    "phone_number": "+14155552671",
    "phone_number_id": "<string>",
    "whatsapp_config_id": 123,
    "variables": {
      "user_name": "Alice",
      "order_id": "ORD-12345",
      "priority": "high"
    },
    "context": {
      "source": "mobile_app",
      "campaign_id": "SUMMER2024"
    },
    "initial_data": {}
  }
}
'

{
  "data": {
    "message": "Workflow execution initiated",
    "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}