Overview
The Exomations API lets your own systems start a flow and follow what happened to the run. Two entry points accept an API key:
| Entry point | Use it to |
|---|---|
| POST /api/trigger/{flowId} | Start an active flow with a JSON payload. |
| POST /api/mcp | Run flows, read runs and build flows from an AI client. See the MCP Server Guide. |
Base URL: https://exomations.com. If your workspace uses its own domain, the same paths work on that domain.
The paths carry no version number (there is no /v1), and there is no separate versioning policy yet.
Authentication
Send your key in the X-Api-Key header on every request. Keys are never accepted in the URL.
X-Api-Key: exo_3f9a... (exo_ followed by 64 hex characters)Create a key
- Sign in as an Admin or Owner and open API Keys in the sidebar.
- Name the key, choose its permissions and, if you want, an expiry date.
- Copy the key when it is shown. It is displayed once; only a SHA-256 hash and the first 8 characters are stored.
Permissions
| Permission | Allows |
|---|---|
| execute | Trigger flows over HTTP and MCP, and read runs over MCP. This is the default. |
| build | Use the MCP building tools: search apps, create, update and validate flows, and activate flows that are already in staging. |
The key form also offers Read Data. No route checks it today, so on its own it opens neither entry point.
- A key belongs to one workspace and works for every flow in it.
- An expired key is refused with 403. To rotate a key, create a new one and delete the old one.
- Creating and deleting keys is written to the audit log.
Start a run
/api/trigger/{flowId}Starts one run of an active flow. Needs the execute permission.
/api/trigger/{tenantId}/{flowId}Same call with your workspace ID in the path. The ID must match the key's workspace.
Request
| Part | Value |
|---|---|
| X-Api-Key | Your API key. Required. |
| Content-Type | application/json |
| X-Webhook-Signature | Required only when a signing secret is set for the workspace. See Signatures. |
| body | Any JSON object, up to 8 MB. It becomes the trigger data; read a field in the flow as {{trigger.order_id}}. |
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,
"Content-Type": "application/json",
},
body: JSON.stringify({ order_id: "1042" }),
});
const run = await res.json(); // { executionId, status: "queued" }
if (res.status !== 202) throw new Error(run.error);import os, requests
res = requests.post(
"https://exomations.com/api/trigger/YOUR_FLOW_ID",
headers={"X-Api-Key": os.environ["EXOMATIONS_KEY"]},
json={"order_id": "1042"},
timeout=15,
)
res.raise_for_status()
run = res.json() # {"executionId": "...", "status": "queued"}The API Keys page shows the URL format. Settings → Communication Channels → Webhook gives the full URL for the flow you pick.
Each endpoint has its own reference page with every response and code samples in cURL, JavaScript and Python: Trigger a flow and Trigger a flow (workspace in the path).
Responses
An accepted call always answers 202. The status field tells you what happened:
{
"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 |
|---|---|
| queued | The run is recorded and waiting 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. |
| duplicate_suppressed | The same body reached the same flow within 10 seconds. No second run was started. |
Signatures
To make sure a call really comes from your system, set a signing secret in Settings → Webhook settings. Once it is set, every trigger call must carry a valid signature as well as the API key. With no secret set, signature headers are ignored.
| Format | Header | Value |
|---|---|---|
| custom | X-Webhook-Signature | Lowercase hex HMAC-SHA256 of the raw body |
| github | X-Hub-Signature-256 | sha256=<hex> |
| shopify | X-Shopify-Hmac-SHA256 | Base64 HMAC-SHA256 of the raw body |
| stripe | Stripe-Signature | t=<timestamp>,v1=<hex>, accepted within 300 seconds |
| clickup | X-Signature | Hex HMAC-SHA256 of the raw body |
| auto | — | Default. Detects which one of the headers above is present. |
import crypto from "node:crypto";
const body = JSON.stringify({ order_id: "1042" }); // sign the exact bytes you send
const signature = crypto
.createHmac("sha256", process.env.EXOMATIONS_WEBHOOK_SECRET)
.update(body)
.digest("hex");
await fetch("https://exomations.com/api/trigger/YOUR_FLOW_ID", {
method: "POST",
headers: {
"X-Api-Key": process.env.EXOMATIONS_KEY,
"X-Webhook-Signature": signature,
"Content-Type": "application/json",
},
body,
});import hashlib, hmac, json, os, requests
body = json.dumps({"order_id": "1042"}).encode() # sign the exact bytes you send
signature = hmac.new(
os.environ["EXOMATIONS_WEBHOOK_SECRET"].encode(), body, hashlib.sha256
).hexdigest()
requests.post(
"https://exomations.com/api/trigger/YOUR_FLOW_ID",
data=body,
headers={
"X-Api-Key": os.environ["EXOMATIONS_KEY"],
"X-Webhook-Signature": signature,
"Content-Type": "application/json",
},
)Duplicate deliveries
Identical bodies sent to the same flow within 10 seconds are treated as one delivery. There is no idempotency-key header. If your sender may retry later than that, add the Idempotency Guard step at the start of the flow and key it on a field of your payload, such as the order number.
Run lifecycle
| Status | Meaning |
|---|---|
| queued | Waiting to start. |
| running | Steps are executing. |
| waiting_approval | Paused at an Approval step until a person decides. |
| retrying | A step failed and is being retried. |
| success | Every step finished. |
| partially_succeeded | The run finished and some steps failed. |
| failed | The run stopped on an error. |
| rejected | An approver rejected it. |
| skipped | The run was not needed and did nothing. |
| held | Waiting for monthly allowance. |
Capacity
| Plan | Runs at the same time | Runs per month |
|---|---|---|
| Starter | 25 | 5,000 |
| Professional | 50 | 10,000 |
| Enterprise | 100 | 25,000 |
- Runs beyond the simultaneous limit wait in the queue. A run that has waited more than one hour fails with a clear message and can be re-run.
- You are warned at 100% of the monthly allowance, runs continue up to 120%, and after that new runs are held, not lost.
Follow a run
Keep the executionId from the trigger response. You can follow the run in three ways:
- From an AI client or script, with your key: call the MCP tool
exo_get_execution. It returns the status, timing and each step's input, output and error. See the MCP Server Guide. - Have the flow tell you: end the flow with an HTTP Request step that posts the result to your system. This is the way to get a callback.
- In the app: open Executions to see every run, step by step.
Rate limits
Each caller may send up to 100 requests a minute across the API and MCP together. The higher figures below are ceilings, not extra allowances.
| Limit | Per minute | Counted per |
|---|---|---|
| All calls, API and MCP together | 100 | caller |
| Trigger calls, ceiling | 200 | flow |
| MCP calls, ceiling | 200 | API key |
| MCP calls, whole workspace | 100 / 200 / 500 | workspace, by plan |
A call over the limit gets 429. Responses carry the standard RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and a 429 carries Retry-After. Wait that long before retrying.
{
"error": "Too many requests, please try again later",
"code": "RATE_LIMIT",
"message": "Too many requests, please try again later"
}Errors
Errors are JSON: error holds the text, message repeats it and code names the kind of error (for example FORBIDDEN).
| HTTP | Message | What to do |
|---|---|---|
| 400 | Flow is not active | Activate the flow, then call again. |
| 401 | API key required. Include X-Api-Key header. | Add the header. |
| 401 | Webhook signature verification failed | Check the secret and sign the raw body. |
| 401 | No webhook signature header found... | A signing secret is set; send the signature header. |
| 403 | Invalid or inactive API key | Check the key or create a new one. |
| 403 | API key expired | Create a new key. |
| 403 | API key lacks execute permission | Use a key with execute. |
| 403 | API key does not match tenant | The workspace ID in the path is not the key's workspace. |
| 403 | Tenant not found or suspended | The workspace is suspended or no longer exists. |
| 404 | Flow not found | Check the flow ID. Flows of other workspaces also answer 404. |
| 413 | request entity too large | Send a smaller body (up to 8 MB). |
| 413 | Payload nesting exceeds the depth limit of 64 | Flatten the body: at most 64 levels deep and 500,000 keys. |
| 413 | The compressed request body expands far beyond its compressed size. Send it uncompressed or split it. | Send the body uncompressed, or split it. |
| 429 | Too many requests, please try again later | Wait for Retry-After. |
| 500 | Trigger failed | Retry; if it repeats, contact support. |
Full reference
The app's own routes (projects, flows, connections, approvals, users, settings, usage) need a signed-in session token, not an API key, and are not part of the public API; scripts and integrations should use an API key with the two entry points above.
/docs/openapi.jsonThe two trigger endpoints and the MCP endpoint as an OpenAPI 3.1 file. Each reference page also has a Markdown copy, listed in /llms.txt.
