# Trigger a flow (workspace in the path)

> Documentation index: https://exomations.com/llms.txt

`POST /api/trigger/{tenantId}/{flowId}`

The same call with your workspace ID in the path.

Works exactly like Trigger a flow, with one more check: the workspace ID in the path must be the workspace the key belongs to, or the call is refused with `403`.

## Authorization

Send an API key with the `execute` permission in the `X-Api-Key` header. Keys are created on the **API Keys** page of the app by an Admin or Owner; the API overview explains permissions, expiry and rotation.

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `tenantId` | string | yes | Your workspace ID. It must be the workspace the API key belongs to. |
| `flowId` | string | yes | The flow's ID. The flow must be active and belong to the key's workspace. |

## Headers

| Name | Required | Description |
|---|---|---|
| `X-Api-Key` | yes | Your API key: `exo_` followed by 64 hex characters. |
| `Content-Type` | no | Send `application/json`. Without it the body is not read: the call is still accepted and the run starts with empty trigger data. |
| `X-Webhook-Signature` | no | Required only when a signing secret is set for the workspace: the lowercase hex HMAC-SHA256 of the raw body. The other accepted formats are listed in the API overview. |

## Body

Any JSON object, up to 8 MB. It becomes the run's trigger data: a field is read in the flow as `{{trigger.order_id}}`. The body is not checked against a schema.

## Responses

### 202

Accepted. `status` says what happened: `queued` (the run waits for a worker), `held` (the workspace is past 120% of its monthly allowance; the run starts by itself after a top-up, an upgrade or the monthly reset) or `duplicate_suppressed` (the same body reached the same flow within 10 seconds and no second run was started; `executionId` is the first delivery's run, or `null` when it is not known).

```json
{
  "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
  "status": "queued"
}
```

```json
{
  "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
  "status": "held",
  "message": "Accepted and held: the workspace is over its monthly execution allowance. The run is recorded and starts automatically after a top-up or upgrade, or when the month resets."
}
```

```json
{
  "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
  "status": "duplicate_suppressed",
  "message": "An identical payload was received for this flow moments ago; this delivery was deduplicated."
}
```

### 400

The flow exists but is not active.

```json
{
  "error": "Flow is not active",
  "code": "VALIDATION",
  "message": "Flow is not active"
}
```

### 401

The `X-Api-Key` header is missing, or a signing secret is set and the signature is missing or does not match.

```json
{
  "error": "API key required. Include X-Api-Key header.",
  "code": "SESSION_EXPIRED",
  "message": "API key required. Include X-Api-Key header."
}
```

```json
{
  "error": "Webhook signature verification failed",
  "code": "SESSION_EXPIRED",
  "message": "Webhook signature verification failed"
}
```

### 403

The key is unknown, inactive or expired, it lacks `execute`, the workspace ID in the path is not the key's workspace, or the workspace is suspended.

```json
{
  "error": "Invalid or inactive API key",
  "code": "FORBIDDEN",
  "message": "Invalid or inactive API key"
}
```

```json
{
  "error": "API key expired",
  "code": "FORBIDDEN",
  "message": "API key expired"
}
```

```json
{
  "error": "API key lacks execute permission",
  "code": "FORBIDDEN",
  "message": "API key lacks execute permission"
}
```

```json
{
  "error": "API key does not match tenant",
  "code": "FORBIDDEN",
  "message": "API key does not match tenant"
}
```

```json
{
  "error": "Tenant not found or suspended",
  "code": "FORBIDDEN",
  "message": "Tenant not found or suspended"
}
```

### 404

No flow with this ID in the key's workspace. Flows of other workspaces also answer `404`.

```json
{
  "error": "Flow not found",
  "code": "NOT_FOUND",
  "message": "Flow not found"
}
```

### 429

Too many calls in a minute. Wait the number of seconds in the `Retry-After` header.

```json
{
  "error": "Too many requests, please try again later",
  "code": "RATE_LIMIT",
  "message": "Too many requests, please try again later"
}
```

```json
{
  "error": "Rate limit exceeded for webhook triggers",
  "code": "RATE_LIMIT",
  "message": "Rate limit exceeded for webhook triggers"
}
```

```json
{
  "error": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly.",
  "code": "RATE_LIMIT",
  "message": "Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly."
}
```

### 413

The body is over 8 MB, or it is nested more than 64 levels deep or has more than 500,000 keys, or it was sent compressed and expands far beyond its compressed size. A body over the size is refused before the flow is looked up and that answer has only a `message` field; the others answer `{ error, code, message }`.

```json
{
  "message": "request entity too large"
}
```

```json
{
  "error": "Payload nesting exceeds the depth limit of 64",
  "code": "PAYLOAD_TOO_LARGE",
  "message": "Payload nesting exceeds the depth limit of 64"
}
```

```json
{
  "error": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.",
  "code": "PAYLOAD_TOO_LARGE",
  "message": "The compressed request body expands far beyond its compressed size. Send it uncompressed or split it."
}
```

### 500

The run could not be recorded. Retry; if it happens again, contact support.

```json
{
  "error": "Trigger failed",
  "code": "SERVER_ERROR",
  "message": "Trigger failed"
}
```

## Examples

### cURL

```bash
curl -X POST https://exomations.com/api/trigger/YOUR_WORKSPACE_ID/YOUR_FLOW_ID \
  -H "X-Api-Key: exo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"1042","customer":{"phone":"+9665XXXXXXXX"}}'
```

### JavaScript

```javascript
const res = await fetch("https://exomations.com/api/trigger/YOUR_WORKSPACE_ID/YOUR_FLOW_ID", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.EXOMATIONS_KEY, // exo_...
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ order_id: "1042", customer: { phone: "+9665XXXXXXXX" } }),
});

const run = await res.json();
if (res.status !== 202) throw new Error(run.error);
console.log(run.executionId, run.status); // "queued", "held" or "duplicate_suppressed"
```

### Python

```python
import os, requests

res = requests.post(
    "https://exomations.com/api/trigger/YOUR_WORKSPACE_ID/YOUR_FLOW_ID",
    headers={"X-Api-Key": os.environ["EXOMATIONS_KEY"]},  # exo_...
    json={"order_id": "1042", "customer": {"phone": "+9665XXXXXXXX"}},
    timeout=15,
)
run = res.json()
if res.status_code != 202:
    raise RuntimeError(run["error"])
print(run["executionId"], run["status"])
```
