# Flow

URL: /business/nouns/flow · Id: `noun:flow`

> A Flow is an ordered path through an App’s Dashboards that takes one Persona from first run to an Offer’s activation Event.

A Flow is an ordered path through an [App](/business/nouns/app)’s [Dashboards](/business/nouns/dashboard) that takes one [Persona](/business/nouns/persona) from first run to an [Offer](/business/nouns/offer)’s activation [Event](/business/nouns/event).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `persona` | [Persona](/business/nouns/persona) | Yes | The Persona it guides; its Role decides which Verbs each step offers. |
| `offer` | [Offer](/business/nouns/offer) | Yes | The Offer whose activation Event ends the Flow; time to value reads from first step to that Event. |
| `steps` | list of [Dashboard](/business/nouns/dashboard) | Yes | The Dashboards in order, first run first, each ending in the Verb that opens the next. |

## Object
```json
{
  "$id": "https://api.sb/petpantry.shop/flows/flow_1",
  "$type": "Flow",
  "persona": "persona_1",
  "offer": "offer_1",
  "steps": [
    "dashboard_1"
  ]
}
```

## Relationships
- <a id="rel-app"></a>A Flow **has** one [App](/business/nouns/app): the Flows an [App](/business/nouns/app) runs on first sign-in, one per [Persona](/business/nouns/persona) and [Offer](/business/nouns/offer), each ending at the activation [Event](/business/nouns/event). `app`, inverse [`guides`](/business/nouns/app#rel-guides).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Flow.create](/business/nouns/flow/create) | Creates a Flow. Inherited from [Noun](/business/nouns/noun). | None. | `Flow.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Flow.get](/business/nouns/flow/get) | Returns one Flow by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Flow.list](/business/nouns/flow/list) | Returns Flows, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Flow.update](/business/nouns/flow/update) | Changes the given properties of a Flow. Inherited from [Noun](/business/nouns/noun). | None. | `Flow.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Flow.delete](/business/nouns/flow/delete) | Deletes a Flow; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Flow.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Flow.create` | Yes | Yes | Yes | No |
| `Flow.get` | Yes | Yes | Yes | Yes |
| `Flow.list` | Yes | Yes | Yes | Yes |
| `Flow.update` | Yes | Yes | Yes | No |
| `Flow.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a flow to Kiln Bakery with a persona and an offer and a dashboard.
```

**API**

```bash
curl -X POST https://api.sb/kilnbakery.com/flows \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persona":"persona_1","offer":"offer_1","steps":["dashboard_1"]}'
```

```json
{
  "api": "https://api.sb/kilnbakery.com",
  "flow": {
    "$id": "https://api.sb/kilnbakery.com/flows/flow_1",
    "$type": "Flow",
    "persona": "persona_1",
    "offer": "offer_1",
    "steps": [
      "dashboard_1"
    ]
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/action_1",
    "operation": "Flow.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const flow = await $.Flow.create({ persona: 'persona_1', offer: 'offer_1', steps: ['dashboard_1'] })
```

**CLI**

```bash
npx startup-builder do Flow.create --json '{"persona":"persona_1","offer":"offer_1","steps":["dashboard_1"]}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Flow.create({ persona: 'persona_1', offer: 'offer_1', steps: ['dashboard_1'] })"
  }
}
```

## Example
The buyer Flow on `stitchly.co` has three steps: describe a garment, pick a tailor, pay for the first [Order](/business/nouns/order). It ends at `Customer.activated`, and time to value is measured across those three steps.