In this Article

• Overview
• Execute Workflow via API 
• Executing Workflow
  • Execute Workflow Using Command Line
  • Execute Workflow Using Postman
• FAQ - Authentication
  • Command Line Authentication
  • Postman Authentication

Overview

Workflows can be executed programmatically using API requests. This capability allows external systems to trigger workflow executions and retrieve their results without using the user interface.

This article explains how to execute a workflow using the API and retrieve its execution status using two approaches:

• Command Line (using curl)

• Postman

Execute Workflow via API

Access the Execute via API Option

1. Open the required Workflow in the application.

2. Navigate to the Designer tab of the workflow.

3. Click the three-dot menu (⋮) located in the top-right corner of the workflow page.

4. From the dropdown menu, select Execute via API.

This option opens the API execution details, where the POST API request used to trigger the workflow execution is displayed. Copy this request to use it in an API.

Executing Workflow

Method 1: Execute Workflow Using Command Line

You can execute the workflow directly from the command line by running the curl command copied from the Execute via API option.

Step 1: Execute the Workflow

Run the copied POST request in your terminal.

Sample POST Request:

curl -X POST "https://<workflow-execution-endpoint>" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"

After running the command, the API returns a response containing an Execution ID.

The Execution ID uniquely identifies the workflow execution and is used to retrieve its execution status.

Step 2: Retrieve Workflow Execution Status

Use the GET API request provided in the Execute via API section and replace the Execution ID placeholder with the ID returned from the previous request.

Sample GET Request:

curl -X GET "https://<workflow-status-endpoint>/<execution_id>" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"

The response returns the workflow execution status and results.

Method 2: Execute Workflow Using Postman

Workflows can also be executed using Postman.

Step 1: Create a Request to Execute the Workflow

1. Open Postman.

2. Create a New Request.

3. Set the request method to POST.

4. Paste the workflow execution API endpoint copied from the Execute via API option into the request URL field.

Add the following header:

Click Send to trigger the workflow execution.

The response will return the Execution ID.

Workflow Inputs

If the workflow defines input parameters, input values can be supplied in the request payload when executing the workflow.

Example workflow input definition:

inputs:
  - param: entity_key
    path: fibernode_id
    type: string
    required: true
    description: Fiber node identifier

The request body should contain key-value pairs where the key matches the input path defined in the workflow.

Example request body:

{
  "fibernode_id": "FN-1001"
}

Workflow inputs are referenced within workflow steps using the input path through the payload object.

Example:

steps:
  - id: start_step
    type: start
    name: Start Workflow
    config:
      message: "Processing fiber node {{ payload.fibernode_id }}"

Important

Use: {{ payload.fibernode_id }}  Do not use: {{ entity_key }}

The payload object contains the workflow input values supplied during workflow execution.

Step 2: Retrieve Workflow Execution Status

Create another request to retrieve the workflow execution status.

1. Create a New Request.

2. Set the method to GET.

3. Paste the GET API endpoint.

4. Replace the Execution ID placeholder with the Execution ID returned from the previous request.

Add the following header:

Click Send to retrieve the workflow execution status and results.

Example Workflow Execution Response:

{
    "workflow_id": 45685509,
    "execution_id": "zGGYs6rfQiuSGMCZ_ZVakg",
    "summary_text": "Workflow 45685509 execution summary.",
    "start_time": "2026-03-16T14:40:51.276597+00:00",
    "end_time": "2026-03-16T14:41:06.077550+00:00",
    "duration_seconds": 13.0,
    "status": "COMPLETED",
    "workflow_details": null,
    "steps": {
        "start_step": {
            "step_id": "start_step",
            "status": "COMPLETED",
            "substatus": null,
            "start_time": "2026-03-16T14:40:51.514654+00:00",
            "end_time": "2026-03-16T14:40:51.611927+00:00",
            "duration_seconds": 0,
            "child_stats": null,
            "child_summaries": null
        },
        "execute_ai_agent": {
            "step_id": "execute_ai_agent",
            "status": "COMPLETED",
            "substatus": null,
            "start_time": "2026-03-16T14:40:52.360918+00:00",
            "end_time": "2026-03-16T14:41:04.612977+00:00",
            "duration_seconds": 12,
            "child_stats": null,
            "child_summaries": null
        },
        "unknown_check_decision": {
            "step_id": "unknown_check_decision",
            "status": "COMPLETED",
            "substatus": null,
            "start_time": "2026-03-16T14:41:05.763895+00:00",
            "end_time": "2026-03-16T14:41:05.887476+00:00",
            "duration_seconds": 0,
            "child_stats": null,
            "child_summaries": null
        },
        "unknown_write_to_db": {
            "step_id": "unknown_write_to_db",
            "status": "PENDING/UNUSED",
            "substatus": null,
            "start_time": null,
            "end_time": null,
            "duration_seconds": null,
            "child_stats": null,
            "child_summaries": null
        },
        "end_step": {
            "step_id": "end_step",
            "status": "PENDING/UNUSED",
            "substatus": null,
            "start_time": null,
            "end_time": null,
            "duration_seconds": null,
            "child_stats": null,
            "child_summaries": null
        }
    }
}

FAQ – Authentication

All API requests require a Bearer access token for authentication.

Command Line Authentication

To obtain an access token from the command line, send a request to the authentication endpoint.

curl -X POST https://auth.dvsum.ai/oauth2/token \
-u "<client_id>:<client_secret>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

Response:

Use the returned access_token in the Authorization header when executing API requests.

Postman Authentication

Postman provides built-in support for OAuth 2.0 and can automatically generate and manage access tokens.

1. Open your Postman Collection or API request.

2. Navigate to the Authorization tab.

3. Select OAuth 2.0 as the Authorization type.

4. Click Get New Access Token.

Configure the following values:

5. Click Get New Access Token.

6. Once the token is generated, click Use Token.

Postman will automatically include the Bearer token in the Authorization header for API requests.

Note: It is recommended to configure authorization at the Postman Collection level so that all API requests automatically inherit the authentication settings.