Running Workflow from API

Modified on Sun, 13 Jul, 2025 at 9:24 PM

Prerequisites: Obtaining API Key

Important
Keep your API key confidential and never commit it to version control. Use environment variables or secure configuration management.

Overview

Execute workflows programmatically using 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

Required Headers

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):

{  "payload": {} }

With input data:

{  "payload":{    "user_id": "12345",     "action": "process_order"     "data": {        "order_id": "ORD-2024-001"        "customer_email": "customer@example.com} }}

Response Format

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