Prerequisites
Obtain an API key from the API settings page.
Keep your API key confidential and never commit it to version control. Use environment variables or secure configuration management.
Overview
Execute workflows programmatically using the Wiv API.
This endpoint triggers a workflow execution and returns tracking information for monitoring progress.
Endpoint Details
HTTP Method & URL
[POST] https://api.wiv.ai/workflows/{workflow_id}/run
Path Parameters
| Parameter | Type | Description |
|---|
workflow_id | string | The unique identifier of the workflow to execute |
| Header | Value | Description |
|---|
Content-Type | application/json | Indicates JSON request body |
X-API-KEY | {your_api_key} | Authentication key (generate in API settings) |
Request Body
{
"payload": {
// Optional: Input data for your workflow
// Structure depends on your workflow's input requirements
}
}
Payload Examples
Empty payload (for workflows with no input requirements):
With input data:
{
"payload": {
"user_id": "12345",
"action": "process_order",
"data": {
"order_id": "ORD-2024-001",
"customer_email": "customer@example.com"
}
}
}
Success Response (200 OK)
{
"data": {
"event_type": "WORKFLOW_TRIGGER",
"execution_id": "exec_abc123def456",
"payload": {
// Echoes back the payload you sent
},
"run_by": "api_user_name",
"tenant_id": "tenant_xyz789",
"timestamp": "2025-05-22 20:59:07.014093",
"trigger_id": "-",
"trigger_type": "MANUAL",
"workflow_id": "workflow_def456ghi789"
}
}
Response Fields
| Field | Type | Description |
|---|
execution_id | string | Unique identifier for this workflow run — use for tracking |
event_type | string | Always WORKFLOW_TRIGGER for manual executions |
timestamp | string | When the workflow was triggered (UTC) |
trigger_type | string | MANUAL for API-triggered workflows |
run_by | string | User or system that initiated the workflow |
tenant_id | string | Your organization identifier |
workflow_id | string | Confirms which workflow was executed |
