API Reference

    Trigger a flow (workspace in the path)

    The same call with your workspace ID in the path.

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

    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.

    For tools and AI agents: this page as Markdown · the public OpenAPI file

    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.

    Needs an API key with the execute permission, sent in the X-Api-Key header.

    Path parameters

    NameTypeRequiredDescription
    tenantIdstringYesYour workspace ID. It must be the workspace the API key belongs to.
    flowIdstringYesThe flow's ID. The flow must be active and belong to the key's workspace.

    Headers

    NameRequiredDescription
    X-Api-KeyYesYour API key: exo_ followed by 64 hex characters.
    Content-TypeNoSend application/json. Without it the body is not read: the call is still accepted and the run starts with empty trigger data.
    X-Webhook-SignatureNoRequired 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"
    }
    StatusMeaningMessage
    400The flow exists but is not active.Flow is not active
    401The 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
    403The 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.Invalid or inactive API key · API key expired · API key lacks execute permission · API key does not match tenant · Tenant not found or suspended
    404No flow with this ID in the key's workspace. Flows of other workspaces also answer 404.Flow not found
    429Too 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.
    413The 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.
    500The 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_WORKSPACE_ID/YOUR_FLOW_ID \
      -H "X-Api-Key: exo_your_key" \
      -H "Content-Type: application/json" \
      -d '{"order_id":"1042","customer":{"phone":"+9665XXXXXXXX"}}'