# exo_update_flow

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

Change a flow's definition, name or description.

A new definition passes the same checks as in `exo_create_flow`; if a check fails, nothing is saved. Step types the flow already has stay allowed; a new step type your plan does not include is refused. Values that `exo_get_flow` returned as `***` keep their stored value, and every step keeps its stored government sign-off setting.

After a change the flow goes back to draft for review. A flow in staging or development can then be switched on in staging with `exo_activate_flow`; a production flow is switched on again by a person in the app. A flow that is live in production stays active and keeps running its published version until a person promotes the change in the app; if it has no separately published version, a definition change is refused.

Permission: `build`.

## Input

| Name | Type | Required | Description |
|---|---|---|---|
| `flowId` | string | yes | The flow id to update. |
| `definition` | object | no | The new flow definition { nodes, edges }. |
| `name` | string | no | New flow name. |
| `description` | string | no | New flow description. |

## Returns

`saved: true`, `flowId`, `status` and `warnings`. For a flow live in production, also `environment: "production"` and `productionPromoted: false`.

## 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`: ``flowId` is required.`
- Tool result with `isError: true`: `Flow "<flowId>" not found.`
- Tool result with `isError: true`: `Flow "<name>" is live in production and has no separately published version, so a definition edit here would change what production runs immediately. …`
- Tool result with `isError: true`: ``definition` must be an object.`
- Tool result with `isError: true`: ``definition` rejected: <reason>.`
- Tool result with `isError: true`: `Flow NOT updated: node(s) <ids> keep a hidden secret ("***") while their destination (url, host, endpoint, connection or step type) changed. …`
- Tool result with `isError: true`: `Flow NOT updated — <n> error(s), <n> warning(s). Fix the errors and retry: <list>`
- Tool result with `isError: true`: `Flow NOT updated — the definition failed the platform staging verifier: <violations>. Fix these issues and retry.`
- Tool result with `isError: true`: `Flow NOT updated — <reason> (step types: <types>). …`
- Tool result with `isError: true`: ``name` must not be empty.`
- Tool result with `isError: true`: `Nothing to update — pass at least one of definition, name, description.`
- Tool result with `isError: true`: `Update failed.`
- 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_update_flow",
    "arguments": {
      "flowId": "7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61",
      "name": "Post new orders to the ERP"
    }
  }
}
```

## Example result

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Flow \"Post new orders to the ERP\" updated and set to DRAFT (id=7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61). Review it, then call exo_activate_flow to reactivate staging.\n{ ... }"
      }
    ],
    "structuredContent": {
      "saved": true,
      "flowId": "7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61",
      "status": "draft",
      "warnings": []
    },
    "isError": false
  }
}
```
