API Reference

    Trigger a flow

    Start one run of an active flow with a JSON payload.

    POST/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

    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
    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, or the workspace is suspended.Invalid or inactive API key · API key expired · API key lacks execute permission · 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_FLOW_ID \
      -H "X-Api-Key: exo_your_key" \
      -H "Content-Type: application/json" \
      -d '{"order_id":"1042","customer":{"phone":"+9665XXXXXXXX"}}'