Skip to main content
POST
Test a flow (hermetic simulator)
Hermetic flow simulator. Walks a flow_config graph against a synthetic transcript without dispatching real tools, writing a call_logs row, or placing a real call. Useful for CI smoke tests, skill verification, and pre-deploy sanity checks. Required scope: flows:test (separate from agents:update because flow tests can spend money on eval LLMs and external APIs in richer test modes).

What this endpoint does

  • Loads the agent’s saved flow_config (or uses the override you supply in the request body).
  • For each conversation node: consumes the next role: "user" turn from your transcript and picks a transition by deterministic keyword overlap with each transition’s label/description. Misses route to “stay”.
  • For each tool-call node: looks up mock_tool_results[step_id]. If error is set, takes the error transition. Otherwise takes success, with custom branches evaluated in declaration order via the jsonpath/equals rule.
  • At an end node (or transfer, or post-end webhook/structured_output), the walk terminates and returns the full trace.

What this endpoint does NOT do

  • It does not call the eval LLM. The deterministic heuristic is good enough for unit tests of branching topology, not for testing prompt quality. For eval-LLM-driven simulation use the in-app Flow Test panel (which runs a real bot pipeline against a WebRTC web call).
  • It does not dispatch tools. Mock every tool-call node you reach via mock_tool_results.
  • It does not write call_logs or fire webhooks.

Body

Optionally include flow_config in the body to test an unsaved draft instead of the agent’s stored graph.

Response

Authorizations

Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Path Parameters

id
string<uuid>
required

Body

application/json
transcript
object[]
required
flow_config
object

Optional override. If omitted, uses the agent's saved flow_config.

mock_tool_results
object

Keyed by tool-call node id.

Response

Trace of nodes visited and decisions made

trace
object[]
named_results
object
slot_values
object
ended_at_step_id
string | null