Trigger RunCopy Anchor Link

Start a saved ActionFlow execution by sending a payload to the public run endpoint. The API runs a saved Start-compatible graph; it does not create an API-specific trigger node or a per-flow /run endpoint.

EndpointCopy Anchor Link

POST /api/runs

curl -X POST 'https://api.actionflows.ai/api/runs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Send a request to see the response.

AuthenticationCopy Anchor Link

Required. External integrations should send an API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

The same route also accepts an authenticated application session, such as a valid signed-in app session cookie. Use an API key for an external integration rather than a session cookie.

API key scope is enforced separately:

• An organization-scoped key is fixed to its organization. The request cannot switch organizations, and the payload organizationId must match that key's organization.
• A user-scoped key has no activeOrganizationId; it must supply an authorized organizationId in the request, and the route checks the caller's organization permission.
• An authenticated application session may use its active or requested organization and checks the session user's permission.

The run's user attribution comes from the authenticated context. The current REST route ignores a client-supplied userId when assigning it.

Request bodyCopy Anchor Link

{
  "payload": {
    "organizationId": "org_123",
    "actionFlowId": "flow_123",
    "inputs": {
      "node_abc_prompt": "Hello"
    },
    "trigger": {
      "body": {
        "event": "order.created"
      },
      "headers": {
        "content-type": "application/json"
      },
      "method": "POST",
      "query": {
        "source": "backend"
      }
    },
    "triggerSource": "api"
  },
  "idempotencyKey": "order-created-ORD-12345",
  "delay": "PT5M",
  "tags": ["production", "api-triggered"],
  "maxAttempts": 3,
  "maxDuration": 3600
}

The request has two layers:

• payload identifies the saved graph and contains optional run inputs and a trigger envelope.
• The remaining top-level fields are execution options.

The REST schema validates the top-level options (delay, idempotencyKey, tags, maxAttempts, and maxDuration), not the nested payload in depth. The route separately checks that payload.actionFlowId and payload.organizationId are present. Nested inputs, trigger, and triggerSource are not schema-validated at this boundary. There is no public payload.data field; use payload.inputs for per-run input overrides.

Request fieldsCopy Anchor Link

payload.inputs uses the same {nodeId}_{inputName} form as the Actionflow Studio Flow Inputs form. A trigger body is separate from input overrides; the trigger fields are merged onto the Start node as body, headers, query, and method.

The canonical Flow triggerSource values are manual, api, webhook, schedule, subflow, and unknown. API-key requests default to api; webhook and scheduled paths set their own source. The route does not reject a non-canonical string at this boundary, so use only the canonical values and do not treat an arbitrary value as a supported trigger or authorization mechanism. subflow is the compatibility/display source for subflow-shaped execution paths; it does not enable the current nested-dispatch limitation described in Subflow.

The Flow task definition currently defaults to one attempt because a retry can repeat non-idempotent side effects. maxAttempts and maxDuration are passed as execution-service overrides; maxDuration is measured in seconds. The gateway validates delay as a string and passes it through; use a supported duration such as PT5M (short execution-service forms such as 30s, 5m, 1h, and 2d are also used).

Validation timingCopy Anchor Link

POST /api/runs first authenticates the request and validates the top-level run options. It treats payload as an unvalidated nested value, then separately checks that payload.actionFlowId and payload.organizationId are present. A payload object missing either required ID returns 400; do not rely on a stable 400 contract for a missing or null payload because those cases are not handled as a documented malformed-envelope response.

After the ID checks, the gateway loads the saved graph and calls validateFlow before enqueueing. The saved graph is validated before payload.inputs and payload.trigger are merged into the execution copy. A run input therefore cannot bypass a missing required value in the saved graph.

A request rejected by these pre-enqueue checks may not create a run-history row. Scheduled dispatch and queue-dispatched runs have different timing; see Scheduled and Queue API.

Success responsesCopy Anchor Link

201 CreatedCopy Anchor Link

The run was dispatched immediately:

{
  "success": true,
  "data": {
    "id": "run_123",
    "runHistoryId": "runhist_123",
    "status": "dispatched",
    "triggerRunId": "run_123"
  }
}

id and triggerRunId identify the runtime run. 201 confirms admission, not completion.

202 AcceptedCopy Anchor Link

The run was placed in the organization queue:

{
  "success": true,
  "data": {
    "position": 2,
    "queueId": "queue_123",
    "runHistoryId": "runhist_123",
    "status": "waiting",
    "triggerRunId": null
  }
}

position can be null. Save queueId and runHistoryId, then use queueId with Get Queued Run. The List Queued Runs endpoint is an active-queue view: it returns only waiting and dispatching items, so it will not show dispatched, failed, or cancelled items. Poll the detail endpoint until it reports one of those states and retrieve triggerRunId when present from that response; then use the runtime ID with Get Run. A 202 does not mean the graph completed.

Error and status behaviorCopy Anchor Link

400: top-level option or required-ID failureCopy Anchor Link

A top-level option failure can return issues; for example, an invalid option produces:

{
  "success": false,
  "error": "Invalid request body",
  "issues": [
    {
      "path": ["maxAttempts"],
      "message": "Expected number"
    }
  ]
}

400: flow validationCopy Anchor Link

A saved graph that fails validateFlow returns validation errors and warnings:

{
  "success": false,
  "error": "Flow validation failed",
  "message": "Flow validation failed",
  "validationErrors": [
    {
      "message": "Node \"sendEmail\" requires input \"to\""
    }
  ],
  "validationWarnings": []
}

Fix and save the reachable graph before retrying. Do not rely on payload.inputs to bypass this check. Validation warnings are returned for review but do not block a run with no validation errors.

401 and 403Copy Anchor Link

401 means the request has no valid API key or authenticated application session. 403 means the authenticated caller cannot access the requested organization or flow. Do not use a different organizationId to probe or access a foreign flow.

404Copy Anchor Link

404 means the flow was not found in the authorized organization. The endpoint does not create a flow and does not expose a /flows/{actionFlowId}/run route.

429Copy Anchor Link

The run-create limiter is keyed by the requested organization and authenticated user. Retry with backoff and keep the same idempotencyKey for the same logical request.

409 and 422 status ownershipCopy Anchor Link

The current REST route does not return 409 for a passive flow and does not return 422 for saved-flow validation. Those statuses belong to the current webhook handler:

• 409 means the webhook found a passive flow and rejected it before enqueue.
• 422 means the webhook's saved graph failed validateFlow before enqueue.

This distinction prevents clients from applying webhook state codes to REST or assuming that a REST 400 is a webhook response.

Idempotency and queue handoffCopy Anchor Link

Use a stable idempotencyKey for retries of one logical request. The local admission record is scoped by organization and actionFlowId; the lookup does not compare request payloads. Reusing a key for a different payload in the same organization and ActionFlow refers to the existing admission. For direct admission, success requires the execution response to contain a runtime id; an otherwise successful response without that id is an admission failure and may leave a history row in executing. A direct duplicate whose existing admission is executing/not dispatched and lacks triggerRunId also fails. These direct-admission failures return a generic REST 500. A dispatched direct duplicate with a triggerRunId is successful and returns 201. In queue mode, a waiting duplicate can be republished, and a dispatched duplicate with a triggerRunId returns HTTP 202 with status: dispatched. A dispatched duplicate without a triggerRunId and failed or cancelled terminal duplicates are unavailable and return a generic REST 500; none is admitted as a new run. Keep the queue ID and the idempotency key while polling or investigating a retry.

The organization tag is added automatically to the run. Caller-supplied organization ownership tags are removed, and organization tags are omitted from public run metadata.

Example requestsCopy Anchor Link

cURLCopy Anchor Link

curl -X POST https://api.actionflows.ai/api/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "organizationId": "org_123",
      "actionFlowId": "flow_123",
      "inputs": { "node_abc_prompt": "Hello" },
      "trigger": { "body": { "event": "order.created" }, "method": "POST" }
    },
    "idempotencyKey": "order-created-ORD-12345",
    "tags": ["production", "api"]
  }'

JavaScriptCopy Anchor Link

const response = await fetch("https://api.actionflows.ai/api/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACTIONFLOWS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payload: {
      organizationId: "org_123",
      actionFlowId: "flow_123",
      inputs: { node_abc_prompt: "Hello" },
    },
    idempotencyKey: "order-created-ORD-12345",
  }),
});

const result = await response.json();
if (response.status === 201) {
  console.log("Run ID:", result.data.id);
} else if (response.status === 202) {
  console.log("Queue ID:", result.data.queueId);
} else {
  console.error(result.error, result.issues, result.validationErrors);
}

RelatedCopy Anchor Link

• API trigger guide
• List Queued Runs
• Queued Run
• Get Run
• Webhook
• TypeScript SDK runs