/api/trigger/{flowId}Sends the request body to the flow's Trigger step and records one run. The call answers at once with 202 and an execution ID; it never waits for the flow to finish. The flow must be active and belong to the key's workspace.
For tools and AI agents: this page as Markdown · the public OpenAPI file
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
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).
{
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"status": "queued"
}{
"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."
}{
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"status": "duplicate_suppressed",
"message": "An identical payload was received for this flow moments ago; this delivery was deduplicated."
}| Status | Meaning | Message |
|---|---|---|
| 400 | The flow exists but is not active. | 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. | API key required. Include X-Api-Key header. · Webhook signature verification failed |
| 403 | The key is unknown, inactive or expired, it lacks execute, or the workspace is suspended. | Invalid or inactive API key · API key expired · API key lacks execute permission · Tenant not found or suspended |
| 404 | No flow with this ID in the key's workspace. Flows of other workspaces also answer 404. | Flow not found |
| 429 | Too many calls in a minute. Wait the number of seconds in the Retry-After header. | Too many requests, please try again later · Rate limit exceeded for webhook triggers · 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 }. | request entity too large · Payload nesting exceeds the depth limit of 64 · 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. | Trigger failed |
Messages are shown exactly as the server sends them, in English. A value in angle brackets is filled in at run time.
Examples
curl -X POST https://exomations.com/api/trigger/YOUR_FLOW_ID \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"order_id":"1042","customer":{"phone":"+9665XXXXXXXX"}}'const res = await fetch("https://exomations.com/api/trigger/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"import os, requests
res = requests.post(
"https://exomations.com/api/trigger/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"])