# 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 <a href="#making-the-request" id="making-the-request"></a>

### Endpoint

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

### Example Request <a href="#example-request" id="example-request"></a>

```
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 <a href="#parameters" id="parameters"></a>

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

{% hint style="info" %}
BASE\_URL, ORG\_ID, FLOW\_ID, and BEARER\_TOKEN will be provided by your Product Team.
{% endhint %}

## Responses <a href="#responses" id="responses"></a>

| 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 <a href="#example-success" id="example-success"></a>

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

### Example — Failure <a href="#example-failure" id="example-failure"></a>

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