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

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.

Route mode requires at least 2 templates with descriptions. With only 1 template, the flow executes it directly regardless of mode.

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 for the full API reference. Quick example:

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