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

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": "[phone]",
    "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": {}
  }
}
'

202

{
  "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

202

application/json

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