# exo_create_flow

> Documentation index: https://exomations.com/llms.txt

Create a new flow. It is always saved as a draft.

The definition is checked before anything is saved: its size (up to 2 MB, 40 levels deep and 20,000 keys), its structure, the platform's staging checks and your plan. If a check fails, nothing is saved and the problems are returned. The flow goes into `projectId`, or into your workspace's first project. A workspace at its plan's flow limit cannot create more. Government sign-off settings sent by the client are dropped: only a person can switch them on in the app.

The new flow is a draft. `exo_activate_flow` refuses flows whose environment is production, which is where every new flow starts, so a person reviews a new flow in the app before it runs.

Permission: `build`.

## Input

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Flow name. |
| `definition` | object | yes | The flow definition { nodes, edges }. |
| `description` | string | no | Optional flow description. |
| `projectId` | string | no | Optional project id. Defaults to your tenant's first project. |
| `triggerType` | string ("webhook" | "manual" | "scheduled" | "form" | "poll_trigger" | "email_trigger" | "voice_call_ended" | "whatsapp_message") | no | Optional trigger type (default 'webhook'). |

## Returns

`saved: true`, `flowId`, `status: "draft"` and `warnings`. When a government sign-off was dropped, `governmentConfirmationIgnored` lists the steps.

## Plan

Each step type belongs to a plan. A create or update that adds a step your workspace's plan does not include is refused before anything is saved, with `code: "PLAN_REQUIRED"`, the plan it needs (`requiredPlan`), the steps involved (`steps`) and the message in English, Arabic and Chinese (`messages`). `exo_get_node_types` marks which steps your plan includes, and `exo_validate_flow` reports them as warnings.

```json
{
  "saved": false,
  "code": "PLAN_REQUIRED",
  "upgradeRequired": true,
  "currentPlan": "starter",
  "requiredPlan": "pro",
  "steps": [
    {
      "nodeId": "sftp_1",
      "type": "sftp",
      "label": "SFTP / FTP Files",
      "family": "advanced_integrations",
      "requiredPlan": "pro"
    }
  ],
  "messages": {
    "en": "Your Starter plan doesn't include these steps: SFTP / FTP Files. They are part of the Professional plan. Nothing was created. Upgrade to Professional, or use steps your plan includes.",
    "ar": "…",
    "zh": "…"
  }
}
```

## Errors

- Tool result with `isError: true`: ``name` is required.`
- Tool result with `isError: true`: ``triggerType` must be one of: <types> (default webhook). Nothing was created.`
- Tool result with `isError: true`: ``definition` object is required.`
- Tool result with `isError: true`: ``definition` rejected: <reason>.`
- Tool result with `isError: true`: `Flow NOT created — <n> error(s), <n> warning(s). Fix the errors and retry: <list>`
- Tool result with `isError: true`: `Flow NOT created — the definition failed the platform staging verifier: <violations>. Fix these issues and retry.`
- Tool result with `isError: true`: `Project "<projectId>" not found in your tenant.`
- Tool result with `isError: true`: `Your tenant has no projects yet. Create a project in the Exomations UI first, then retry.`
- Tool result with `isError: true`: `Maximum flow limit (<n>) reached for your plan. Delete a flow or upgrade.`
- Tool result with `isError: true`: `Flow NOT created — <reason> (step types: <types>). …`
- JSON-RPC -32001 (HTTP 403): `API key lacks the 'build' permission required for flow authoring tools`

## Example call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "exo_create_flow",
    "arguments": {
      "name": "Post new orders",
      "definition": {
        "nodes": [
          {
            "id": "trigger_1",
            "type": "trigger",
            "position": {
              "x": 0,
              "y": 0
            },
            "data": {
              "nodeType": "trigger",
              "label": "Webhook",
              "config": {}
            }
          },
          {
            "id": "http_1",
            "type": "http_request",
            "position": {
              "x": 260,
              "y": 0
            },
            "data": {
              "nodeType": "http_request",
              "label": "Post order",
              "config": {
                "url": "https://example.com/orders",
                "method": "POST",
                "body": "{{trigger.order_id}}"
              }
            }
          }
        ],
        "edges": [
          {
            "id": "e1",
            "source": "trigger_1",
            "target": "http_1"
          }
        ]
      }
    }
  }
}
```

## Example result

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Flow \"Post new orders\" created as a DRAFT (id=7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61). A person reviews and activates it in the Exomations app; exo_activate_flow refuses a flow whose environment is production, which is where every new flow starts.\n{ ... }"
      }
    ],
    "structuredContent": {
      "saved": true,
      "flowId": "7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61",
      "status": "draft",
      "warnings": []
    },
    "isError": false
  }
}
```
