Skip to main content
POST
/
agents
/
{id}
/
flow
/
test
Test a flow (hermetic simulator)
curl --request POST \
  --url https://api.goyappr.com/agents/{id}/flow/test \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transcript": [
    {
      "text": "<string>"
    }
  ],
  "mock_tool_results": {}
}
'
{
  "trace": [
    {
      "step_id": "<string>",
      "decision": "<string>",
      "reason": "<string>",
      "data": {}
    }
  ],
  "named_results": {},
  "slot_values": {},
  "ended_at_step_id": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.goyappr.com/llms.txt

Use this file to discover all available pages before exploring further.

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

{
  "transcript": [
    { "role": "user", "text": "I want to book for next Wednesday at 2pm" }
  ],
  "mock_tool_results": {
    "check-availability-step": {
      "result": { "status": "available", "slot_id": "abc123" }
    }
  }
}
Optionally include flow_config in the body to test an unsaved draft instead of the agent’s stored graph.

​
Response

{
  "trace": [
    { "step_id": "start-1", "kind": "enter" },
    { "step_id": "start-1", "kind": "auto_advance", "decision": "ask-date-1" },
    { "step_id": "ask-date-1", "kind": "enter" },
    { "step_id": "ask-date-1", "kind": "eval", "decision": "tx-confirm", "reason": "heuristic match (overlap_score=2)" },
    { "step_id": "check-availability-step", "kind": "enter" },
    { "step_id": "check-availability-step", "kind": "tool_mock", "decision": "confirm-step", "reason": "success", "data": { "status": "available", "slot_id": "abc123" } },
    { "step_id": "end-1", "kind": "enter" },
    { "step_id": "end-1", "kind": "end" }
  ],
  "named_results": { "Check Availability": { "status": "available", "slot_id": "abc123" } },
  "slot_values": {},
  "ended_at_step_id": "end-1"
}

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