Executing Flow via API (Headless Execution)

Agentic flows are typically triggered by a webchat, channel integration, or another UI surface. Sometimes, you may need to run a flow programmatically — for example, to:

• Integrate the flow into a custom application or backend process.

• Trigger automation without a user interface (headless execution).

• Run tests or batch processes against a flow.

This API endpoint lets you directly execute an existing flow without requiring a connected front end.

When you execute a flow this way, it runs exactly as if a user had triggered it through a channel. The flow can take input variables, process logic, and — if configured — call external services to store results.

Making the Request

Endpoint

POST <BASE_URL>/cgw/process/v1/orgs/<ORG_ID>/flows/<FLOW_ID>/execute

Example Request

curl --location '<BASE_URL>/cgw/process/v1/orgs/<ORG_ID>/flows/<FLOW_ID>/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <BEARER_TOKEN>' \
--data '{
  "<VARIABLE_1>": "<VARIABLE_1_VALUE>",
  "<VARIABLE_2>": "<VARIABLE_2_VALUE>"
}'

Parameters

Variable	Description
BASE_URL	URL of the API Gateway hosting your instance
ORG_ID	The organization ID that contains the flow you want to execute
FLOW_ID	The ID of the flow you want to run
BEARER_TOKEN	Authentication token needed for API access
Request Body	Optional JSON key-value pairs representing variables your flow expects (multiple allowed)

BASE_URL, ORG_ID, FLOW_ID, and BEARER_TOKEN will be provided by your Product Team.

Responses

HTTP Status Codes	Description
200 OK	Flow executed successfully
400 Bad Request	Invalid request body or missing required variables
401 Unauthorized	Invalid or missing bearer token
404 Not Found	ORG_ID or FLOW_ID not found
500 Internal Server Error	Unexpected issue during execution

Example — Success

{
    "sessionId": "6e16376b-fd09-4a9a-a49a-9ba4c3901563",
    "result": "Execution completed"
}

Example — Failure

{
    "error": "Failed to execute flow 8c996034-eeff-4efc-b04e-4fb410d6f2b"
}

If your flow needs to return data, it must include a step (such as a REST call) to push results to your system. This endpoint itself only reports execution status.