> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pepline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation flows

> Read and author an agent's conversation — its phases and the answers each one captures.

A flow is an ordered set of **phases**. Each phase has an objective, exit criteria, the tools it may use, and the **slots** it captures — the data the phase collects, and, for enum-typed slots, the quick-reply chips a visitor sees. The structural vocabulary (phase kind, transitions, guards) is read-only; you author the prose and the slots.

Every write below trial-compiles. An illegal change answers `422 flow_invalid` and rolls back — the live flow only ever moves between valid states.

## Read the flow

```bash theme={null}
curl https://app.pepline.ai/api/v1/agents/sales-intake/flow \
  -H "Authorization: Bearer pep_sk_..."
```

Returns the active flow: its phases in order, each with its slots.

## Author and edit phases

```bash theme={null}
# Add a phase (lands just before the closing phase)
curl https://app.pepline.ai/api/v1/agents/sales-intake/flow/states \
  -H "Authorization: Bearer pep_sk_..." -H "Content-Type: application/json" \
  -d '{ "title": "Scope the work", "objective": "Understand what they want built",
        "exit_criteria": "The core deliverable is clear", "max_turns": 4,
        "tools": ["consult_knowledge", "capture_slots"] }'
```

The phase `key` is minted from the title once and is identity afterwards — renaming the title never changes it. Then:

* **Edit** the prose and tools: `PATCH /flow/states/{id}`.
* **Reorder**: `PATCH /flow/states/{id}/position` with `{ "direction": "up" }` or `"down"` — a neighbour swap among the live phases. The closing phase stays pinned last.
* **Archive / restore**: `POST` / `DELETE` on `/flow/states/{id}/archive`.

## Slots — the answers a phase captures

```bash theme={null}
curl https://app.pepline.ai/api/v1/agents/sales-intake/flow/states/{id}/slots \
  -H "Authorization: Bearer pep_sk_..." -H "Content-Type: application/json" \
  -d '{ "key": "budget_band", "title": "Budget", "data_type": "band",
        "enum_values": ["under_10k", "10k_30k", "30k_plus"], "required": true }'
```

`data_type` is one of `string`, `enum`, `band`, `boolean`, `email`; `enum` and `band` require `enum_values` (the chip values). Edit with `PATCH /flow/slots/{id}`, archive/restore under `/flow/slots/{id}/archive`.

A phase's schema is capped at **16 slots** — overflow is the most common `422 flow_invalid`.

## Tools

A phase's tools decide what it may do: `consult_knowledge` (ground replies in activated knowledge), `capture_slots` (record the configured answers), `suggest_replies` (one-tap chips), `offer_deliverable` (promise and trigger the wrap-up document). Set the full list with `PATCH /flow/states/{id}` — removing `capture_slots` from a phase that still has required answers is refused.