Start an existing ActionFlow from your backend with POST /api/runs. There is no per-flow /flows/{id}/run URL.

API

Any saved ActionFlow in your organization can be started from code. You do not pick an "API" start-node type. Add a Start, Start Scheduled, or Start Subflow node in Actionflow Studio, then call the public run API.

Endpoint

POST https://api.actionflows.ai/api/runs

Authenticate with an organization API key (Authorization: Bearer …). See API Introduction and Trigger Run.

There is no https://api.actionflows.ai/flows/{flowId}/run URL. That path is not part of the API.

Request

{
  "payload": {
    "organizationId": "org_123",
    "actionFlowId": "flow_123",
    "inputs": {
      "node_abc_prompt": "Hello"
    },
    "trigger": {
      "body": { "hello": "world" },
      "headers": { "content-type": "application/json" },
      "method": "POST",
      "query": {}
    },
    "triggerSource": "api"
  },
  "idempotencyKey": "optional-unique-key",
  "delay": "5m",
  "tags": ["production", "api-triggered"]
}

payload.inputs uses the same {nodeId}_{inputName} keys as the Actionflow Studio Flow Inputs form.
payload.trigger is merged onto the start node (body, headers, query, method).
Organization-scoped API keys inherit the org; user-scoped keys must send organizationId.

The flow is validated before enqueue (validateFlow). Invalid graphs return 400 with validation errors.

When the organization concurrency limit is reached, the response is 202 with a queueId. Poll List Queued Runs.

Example

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": { "hello": "world" }, "method": "POST" },
      "triggerSource": "api"
    },
    "idempotencyKey": "run-123",
    "tags": ["api"]
  }'

const response = await fetch("https://api.actionflows.ai/api/runs", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payload: {
      organizationId: "org_123",
      actionFlowId: "flow_123",
      inputs: { node_abc_prompt: "Hello" },
      trigger: { body: { hello: "world" }, method: "POST" },
      triggerSource: "api",
    },
    idempotencyKey: `run-${Date.now()}`,
    tags: ["api"],
  }),
});
const data = await response.json();
const runId = data.data?.id;

Hosted MCP uses run_actionflow with the same inputs, trigger, delay, and tags. The server builds this REST payload. See Hosted MCP Server.

Trigger Run
Webhook when an external system should POST to ActionFlows instead
Manual and Scheduled start nodes

API

API

Endpoint

Request

Example

Related

On this page