# Overview

Flows are the core building block of PromptShuttle. A flow packages your prompt templates, model configuration, and tool assignments into a versioned, deployable unit.

## Why flows?

Without flows, prompt management quickly becomes painful:

* Prompts are hardcoded in your application, requiring redeployment to change them
* No audit trail of what changed, when, and by whom
* No way to A/B test or gradually roll out prompt changes
* No separation between environments (dev/staging/production)

Flows solve all of this. You edit prompts in PromptShuttle, version them, and promote across environments — your application code stays the same.

## Structure

```
Flow (e.g. "customer_support")
├── Version 1 (activated in production)
│   ├── Template: "main" (entrypoint)
│   ├── Template: "billing_handler"
│   └── Template: "technical_handler"
├── Version 2 (activated in development)
│   ├── Template: "main" (entrypoint, updated prompt)
│   ├── Template: "billing_handler"
│   └── Template: "technical_handler" (new model)
└── Version 3 (draft, editable)
    └── ...
```

* **Flow** — A named container. Has a slug (e.g. `customer_support`) used in API URLs.
* **Version** — An immutable snapshot of templates (once activated). Fork to create a new editable version.
* **Template** — A single prompt with model config, tools, and parameters. One template is the entrypoint.

## Creating a flow

### Via the UI

1. Go to **Flows** and click **Create Flow**
2. Enter a title — the slug name is auto-generated
3. A first version with a "main" template is created automatically
4. Edit the template prompt, select a model, and save

### Via the API

```bash
curl -X POST https://app.promptshuttle.com/api/v1/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Support"
  }'
```

## Execution modes

### Direct mode (default)

The entrypoint template runs directly. Best for single-purpose flows.

### Route mode

An LLM classifier analyzes the user's input and selects the best template based on each template's `description` field. This is useful for flows that handle multiple intents.

For example, a customer support flow might have:

| Template            | Description                                      |
| ------------------- | ------------------------------------------------ |
| `billing_handler`   | Handles billing questions, refunds, and payments |
| `technical_handler` | Handles technical issues and bug reports         |
| `general_handler`   | Handles general inquiries and feedback           |

The classifier model defaults to `openai/gpt-4o-mini` but can be overridden per flow via the `classifierModel` field.

{% hint style="info" %}
Route mode requires at least 2 templates with descriptions. With only 1 template, the flow executes it directly regardless of mode.
{% endhint %}

## Version lifecycle

```
Create/Fork  →  Edit  →  Activate  →  (Read-only)
                             │
                             └→  Fork into new version
```

1. **Create** a new empty version, or **fork** an existing version to start from its templates
2. **Edit** templates freely while the version is in draft state
3. **Activate** the version for an environment (e.g. `production`)
4. Activated versions are read-only. Fork again to make changes.

## Multi-template flows

A version can contain multiple templates. This enables:

* **Composition** — Templates can reference each other as sub-templates via `[[other_template_name]]` parameter syntax
* **Agent orchestration** — Templates can invoke other templates as sub-agents via Agent tools
* **Route mode** — The classifier picks the best template per request

## Running a flow

See [Flow Execution API](https://docs.promptshuttle.com/api-reference/flow-execution) for the full API reference. Quick example:

```bash
curl -X POST https://app.promptshuttle.com/api/v1/flows/customer_support/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": { "customer_name": "Alice" },
    "environment": "production"
  }'
```

## Managing flows via API

| Method   | Endpoint                                                   | Description                  |
| -------- | ---------------------------------------------------------- | ---------------------------- |
| `GET`    | `/api/v1/flows`                                            | List all flows               |
| `GET`    | `/api/v1/flows/{flowId}`                                   | Get a flow by ID             |
| `POST`   | `/api/v1/flows`                                            | Create a new flow            |
| `PUT`    | `/api/v1/flows/{flowId}`                                   | Update flow metadata         |
| `DELETE` | `/api/v1/flows/{flowId}`                                   | Soft-delete a flow           |
| `POST`   | `/api/v1/flows/{flowId}/versions`                          | Create a new empty version   |
| `POST`   | `/api/v1/flows/{flowId}/versions/{versionId}/fork`         | Fork a version               |
| `POST`   | `/api/v1/flows/{flowId}/versions/{versionId}/environments` | Activate for an environment  |
| `GET`    | `/api/v1/flows/{flowId}/parameters`                        | Discover expected parameters |