Conversation flows

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

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

# 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

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.

Getting started

Authoring

Guides

Conventions

Read the flow

Author and edit phases

Slots — the answers a phase captures

Tools

​Read the flow

​Author and edit phases

​Slots — the answers a phase captures

​Tools

Read the flow

Author and edit phases

Slots — the answers a phase captures

Tools