# create_flow

Returns ok, flowId, status and the next review step, or definition validation errors..

## Purpose

Create a DRAFT flow from a template key and/or a definition. Nothing runs until set_flow_status live. Returns validation errors with JSON paths if the definition is invalid.

## Credentials and scope

Owner workspace credential. The credential determines tool visibility. For tools with appId, use the HeyCrust app UUID from list_apps; the dashboard app selector does not supply MCP arguments for you.

## Inputs

- `name`: required; string; minLength: 1; maxLength: 80
- `templateKey`: optional; string
- `definition`: optional complete FlowDefinition object. See the [nested definition contract](/docs/mcp/flow-definition); structure and business checks are validated by the handler.

## Example request

The identifiers and merchant are fictional. Replace them with records returned for your own workspace; this example is schema-checked, not a promise that the fictional record exists.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_flow",
    "arguments": {
      "name": "Welcome on install",
      "templateKey": "welcome"
    }
  }
}
```

POST this JSON to `https://heycrust.com/api/mcp` with `Content-Type: application/json` and `Authorization: Bearer <YOUR_CREDENTIAL>`. The tool result normally contains JSON encoded as text in `result.content`; inspect JSON-RPC errors and `result.isError` before using it.

## Result

Returns ok, flowId, status and the next review step, or definition validation errors.

## Effects and verification

Creates a draft Flow. No automation runs until it is activated. A template key must come from list_flow_templates; a supplied definition is checked by the real Flow definition validator.

## Troubleshooting

A missing tool can mean that the credential lacks its catalog or required scopes. Invalid arguments are different from unavailable source data or a record outside the workspace. A handler can return a business error even when the argument schema is valid. Read [MCP overview](/docs/mcp) and [Help](/docs/help).