Developers

    API Reference

    Start flows from your own systems and follow every run.

    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 pointUse it to
    POST /api/trigger/{flowId}Start an active flow with a JSON payload.
    POST /api/mcpRun 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.

    Every run is asynchronous. A trigger call returns at once with an execution ID; it does not wait for the flow to finish.

    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

    1. Sign in as an Admin or Owner and open API Keys in the sidebar.
    2. Name the key, choose its permissions and, if you want, an expiry date.
    3. Copy the key when it is shown. It is displayed once; only a SHA-256 hash and the first 8 characters are stored.

    Permissions

    PermissionAllows
    executeTrigger flows over HTTP and MCP, and read runs over MCP. This is the default.
    buildUse 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

    POST/api/trigger/{flowId}

    Starts one run of an active flow. Needs the execute permission.

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

    Same call with your workspace ID in the path. The ID must match the key's workspace.

    Request

    PartValue
    X-Api-KeyYour API key. Required.
    Content-Typeapplication/json
    X-Webhook-SignatureRequired only when a signing secret is set for the workspace. See Signatures.
    bodyAny 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"}}'

    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"
    }
    StatusMeaning
    queuedThe run is recorded and waiting for a worker.
    heldThe workspace is past 120% of its monthly allowance. The run starts by itself after a top-up, an upgrade or the monthly reset.
    duplicate_suppressedThe 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.

    FormatHeaderValue
    customX-Webhook-SignatureLowercase hex HMAC-SHA256 of the raw body
    githubX-Hub-Signature-256sha256=<hex>
    shopifyX-Shopify-Hmac-SHA256Base64 HMAC-SHA256 of the raw body
    stripeStripe-Signaturet=<timestamp>,v1=<hex>, accepted within 300 seconds
    clickupX-SignatureHex 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,
    });
    Sign the exact bytes you send. Re-serialising the JSON after signing changes the bytes and the check fails with 401.

    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

    StatusMeaning
    queuedWaiting to start.
    runningSteps are executing.
    waiting_approvalPaused at an Approval step until a person decides.
    retryingA step failed and is being retried.
    successEvery step finished.
    partially_succeededThe run finished and some steps failed.
    failedThe run stopped on an error.
    rejectedAn approver rejected it.
    skippedThe run was not needed and did nothing.
    heldWaiting for monthly allowance.

    Capacity

    PlanRuns at the same timeRuns per month
    Starter255,000
    Professional5010,000
    Enterprise10025,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.
    The trigger endpoint has no callback URL parameter, and the HTTP reply never waits for the flow.

    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.

    LimitPer minuteCounted per
    All calls, API and MCP together100caller
    Trigger calls, ceiling200flow
    MCP calls, ceiling200API key
    MCP calls, whole workspace100 / 200 / 500workspace, 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).

    HTTPMessageWhat to do
    400Flow is not activeActivate the flow, then call again.
    401API key required. Include X-Api-Key header.Add the header.
    401Webhook signature verification failedCheck the secret and sign the raw body.
    401No webhook signature header found...A signing secret is set; send the signature header.
    403Invalid or inactive API keyCheck the key or create a new one.
    403API key expiredCreate a new key.
    403API key lacks execute permissionUse a key with execute.
    403API key does not match tenantThe workspace ID in the path is not the key's workspace.
    403Tenant not found or suspendedThe workspace is suspended or no longer exists.
    404Flow not foundCheck the flow ID. Flows of other workspaces also answer 404.
    413request entity too largeSend a smaller body (up to 8 MB).
    413Payload nesting exceeds the depth limit of 64Flatten the body: at most 64 levels deep and 500,000 keys.
    413The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.Send the body uncompressed, or split it.
    429Too many requests, please try again laterWait for Retry-After.
    500Trigger failedRetry; 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.

    GET/docs/openapi.json

    The 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.

    Build your first integration today.

    7-day trial1 SAR card checkHosted in Riyadh