{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-create-customer-flow-input-schema.json",
  "title": "CreateCustomerFlowInput",
  "description": "Input for creating a customer flow. SCRIPTED writes the conversation out as a graph of turns; IMPROV gives the simulated customer a brief and lets it improvise.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/roark-customer-flow-api-openapi.yml#/components/schemas/CreateCustomerFlowInput",
  "oneOf": [
    {
      "$ref": "#/$defs/CreateScriptedCustomerFlowInput"
    },
    {
      "$ref": "#/$defs/CreateImprovCustomerFlowInput"
    }
  ],
  "$defs": {
    "CreateImprovCustomerFlowInput": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "IMPROV"
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "agentExpectations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlowExpectationInput"
          }
        },
        "agentIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "minItems": 1,
          "description": "Agents this flow exercises. At least one is required for improv flows."
        },
        "happyPath": {
          "$ref": "#/$defs/FlowHappyPathInput"
        },
        "edgeCases": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlowEdgeCaseInput"
          },
          "description": "Other ways of running it, each inheriting from the happy path what it does not name."
        }
      },
      "required": [
        "type",
        "title",
        "agentIds",
        "happyPath"
      ],
      "title": "Improv"
    },
    "CreateScriptedCustomerFlowInput": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "SCRIPTED"
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "agentExpectations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlowExpectationInput"
          }
        },
        "agentIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "default": [],
          "description": "Agents this flow exercises. Optional for scripted flows."
        },
        "scriptAdherence": {
          "type": "string",
          "enum": [
            "LOOSE",
            "STRICT"
          ],
          "description": "How closely a run follows the script. LOOSE (default) hands the whole script to the simulated customer as one prompt; it keeps the call moving whatever your agent says. STRICT runs the script as a state machine on the agent service: at every agent step the simulated customer waits, silent, until your agent has said the expected line, and only then moves on. Scripted flows only; STRICT needs the agent-service transport and is not available on realtime models. (LOOSE is the default.)"
        },
        "offScriptPolicy": {
          "oneOf": [
            {
              "$ref": "#/$defs/OffScriptPolicy"
            },
            {
              "type": "null"
            }
          ]
        },
        "branchingMode": {
          "type": "string",
          "enum": [
            "DETERMINISTIC",
            "ADAPTIVE"
          ],
          "description": "How a run walks the graph. DETERMINISTIC (\"Simulate every path\" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE (\"Adapt to your agent\") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade. (DETERMINISTIC is the default.)"
        },
        "graph": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlowStep"
          },
          "minItems": 1,
          "description": "The conversation, as a graph of steps. At most 100 steps across at most 25 paths. The variants come from the graph: one per path, so they are not sent here. A CUSTOMER_TURN describes what the simulated customer says and the persona phrases it; a CUSTOMER_VERBATIM_TURN is said word for word."
        }
      },
      "required": [
        "type",
        "title",
        "graph"
      ],
      "title": "Scripted"
    },
    "FlowEdgeCaseInput": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1
        },
        "environmentId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "prompt": {
          "type": [
            "string",
            "null"
          ]
        },
        "precededByCustomerFlowId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "precededByCustomerFlowVariantId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "includeFlowExpectations": {
          "type": "boolean",
          "description": "Whether this edge case is graded on the flow's agentExpectations as well as its own additionalExpectations. Defaults to true; false grades it on its additionalExpectations only."
        },
        "additionalExpectations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlowExpectationInput"
          },
          "description": "The expectations graded on this variant only, on top of the flow's own. Sent as the complete set: it replaces whatever the variant had, so omit it to leave the set alone and send [] to clear it. Improv flows only: a scripted variant's expectations come from the agent turns on its path and are rewritten on every graph edit."
        },
        "personaOverrideId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "The persona this runs as. Omit to inherit the happy path's."
        }
      },
      "required": [
        "title"
      ]
    },
    "FlowExpectationInput": {
      "type": "object",
      "properties": {
        "prompt": {
          "type": "string",
          "minLength": 1,
          "description": "What the agent under test is graded against."
        }
      },
      "required": [
        "prompt"
      ]
    },
    "FlowHappyPathInput": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1
        },
        "environmentId": {
          "type": "string",
          "format": "uuid",
          "description": "The conditions this flow runs under. Edge cases inherit them unless they name their own."
        },
        "prompt": {
          "type": [
            "string",
            "null"
          ]
        },
        "precededByCustomerFlowId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "precededByCustomerFlowVariantId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "additionalExpectations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlowExpectationInput"
          },
          "description": "The expectations graded on this variant only, on top of the flow's own. Sent as the complete set: it replaces whatever the variant had, so omit it to leave the set alone and send [] to clear it. Improv flows only: a scripted variant's expectations come from the agent turns on its path and are rewritten on every graph edit."
        },
        "personaOverrideId": {
          "type": "string",
          "format": "uuid",
          "description": "The persona this flow runs as. Edge cases inherit it unless they name their own."
        }
      },
      "required": [
        "title",
        "environmentId",
        "personaOverrideId"
      ],
      "description": "The way this flow is meant to go."
    },
    "FlowStep": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "AGENT_TURN"
            },
            "content": {
              "type": [
                "string",
                "null"
              ]
            },
            "offScriptPolicy": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "reaction": {
                  "type": "string",
                  "enum": [
                    "STAY_SILENT",
                    "REPEAT",
                    "RESPOND",
                    "SAY"
                  ],
                  "default": "STAY_SILENT"
                },
                "sayLine": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1,
                  "maxLength": 2000
                },
                "maxAttempts": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 20,
                  "default": 3
                },
                "then": {
                  "type": "string",
                  "enum": [
                    "HANG_UP",
                    "MOVE_ON",
                    "ADAPT",
                    "HANG_UP_INVALIDATE"
                  ],
                  "default": "HANG_UP"
                },
                "waitSeconds": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 600
                }
              },
              "required": [
                "reaction",
                "maxAttempts",
                "then"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "CUSTOMER_TURN"
            },
            "content": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "CUSTOMER_FIRST_MESSAGE"
            },
            "content": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "CUSTOMER_VERBATIM_TURN"
            },
            "content": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "CUSTOMER_SILENCE"
            },
            "silenceDurationSeconds": {
              "type": [
                "integer",
                "null"
              ],
              "exclusiveMinimum": 0
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "CUSTOMER_DTMF"
            },
            "dtmfDigits": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "AGENT_DTMF"
            },
            "dtmfDigits": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "VOICEMAIL"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "CUSTOMER_HANDOFF"
            },
            "handoffPersonaId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "format": "uuid"
            },
            "ref": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "steps": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/FlowStep"
              }
            },
            "mergeIntoNodeIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "stage": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "required": {
                  "type": "boolean"
                },
                "analyze": {
                  "type": "boolean"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "type": {
              "type": "string",
              "const": "SCENARIO_LINK"
            },
            "linkedCustomerFlowId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            },
            "linkedCustomerFlowVariantId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        }
      ],
      "description": "One step in a scripted flow's conversation.\n\n`nodeId` is the identity contract: include it to update the existing step, omit it to create a new one.\nA step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which\nnames steps elsewhere in the same request that this step rejoins. Branches that come back together are\nrepresented that way rather than by repeating the shared step, so reading a flow, editing it and writing\nit back preserves it exactly.\n\nA merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in\nthe same request. `ref` is a label you choose, it is request-local, and it is never stored or returned.\nPut the shared step inline under the first branch that reaches it and point the others at it: a top-level\nstep is a root wired straight from the start of the flow, so a merge target parked there would also be\nreachable directly.\n\nA `CUSTOMER_TURN` describes what the simulated customer says and the persona phrases it; a\n`CUSTOMER_VERBATIM_TURN` is said word for word, and one placed as a top-level step opens the call\nthe moment it connects, before the agent speaks. `CUSTOMER_FIRST_MESSAGE` is the retired name for\nthat opening case: still accepted, stored and returned as `CUSTOMER_VERBATIM_TURN`.\n\nThe two DTMF types are mirror images and both require `dtmfDigits`. `CUSTOMER_DTMF` is keys the\nsimulated caller presses while navigating your agent. `AGENT_DTMF` is keys your agent under test is\nexpected to press while navigating a menu the simulation is playing, so its digits are an assertion the\nrun is graded against rather than an instruction, and it counts as an agent turn for role alternation.\n\nA `CUSTOMER_HANDOFF` hands the phone to another persona (`handoffPersonaId`), or back to the flow's\nown persona when it is null. The steps after it are spoken by whoever holds the phone. It sits between\nturns like a silence, so it may follow either side.\n\nIn a STRICT flow an `AGENT_TURN` may carry its own `offScriptPolicy`, which replaces the flow-level one at\nthat step. Omit it (or send null) to follow the flow's policy. Use it where one missed step makes the rest\nof the call meaningless: an authentication menu, say, with `then: HANG_UP_INVALIDATE`.\n\nAny step may set `stage`, the named phase of the flow it belongs to: the IVR, the login, the scenario\nitself. Steps in one stage are drawn as a group in the editor, and the name is yours: the reports say it\nback to you. The stage does not have to exist first, it is created the first time a step names it, and a\nname already in the project is matched ignoring case.\n\nA stage with `required: true` is a gate. A run that ends without getting PAST it never reached what was\nbeing measured, so it stays in the report, labelled with the stage it never completed and the one it\nstopped in, and is left out of the run score and the success-criteria verdict: an agent that never clears\nthe IVR does not fail every check in a scenario it never started. `required` belongs to the stage rather\nthan to the step, so a read returns it on every step in that stage, and a write that sets it on any one\nof them marks the whole stage. A flow that requires no stage is scored exactly as before.\n\nA stage with `analyze: false` is not measured. Its turns are kept out of the core call metrics (talk\ntime, speech pace, turn and response timings), which is what an IVR usually wants alongside\n`required: true`: the run has to get through the menu, but how the agent sounded reading it is not what\nis being tested. Coverage is being extended package by package, so the judged metrics (quality,\ncompliance, repetition, escalation, tone) still read the whole call for now. Nothing is cut and nothing\nis re-timed, so a turn at 4:10 is still at 4:10 with an earlier stage excluded, and rate metrics divide\nby the part of the call that was measured rather than by the whole of it. Defaults to true, belongs to\nthe stage the same way `required` does, and turning it off on any one step turns it off for the stage."
    },
    "OffScriptPolicy": {
      "type": "object",
      "properties": {
        "reaction": {
          "type": "string",
          "enum": [
            "STAY_SILENT",
            "REPEAT",
            "RESPOND",
            "SAY"
          ],
          "default": "STAY_SILENT"
        },
        "sayLine": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 2000
        },
        "maxAttempts": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 3
        },
        "then": {
          "type": "string",
          "enum": [
            "HANG_UP",
            "MOVE_ON",
            "ADAPT",
            "HANG_UP_INVALIDATE"
          ],
          "default": "HANG_UP"
        },
        "waitSeconds": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 600
        }
      },
      "required": [
        "reaction",
        "maxAttempts",
        "then"
      ],
      "description": "STRICT only. What the simulated customer does when your agent does not say the expected line. Each unmatched agent utterance is an attempt: `reaction` runs per attempt (STAY_SILENT, REPEAT its last scripted line, RESPOND once in character without moving on, or SAY `sayLine`), and `then` runs when attempts reach `maxAttempts` or your agent stays silent for `waitSeconds` (HANG_UP ends the call with ended reason SCRIPT_DIVERGED, HANG_UP_INVALIDATE ends it the same way and invalidates the run so it is scored by nothing and counted nowhere, MOVE_ON advances anyway, ADAPT hands the rest of the call to loose behaviour). Null: stay silent, 3 attempts, hang up. The default for every agent step; an AGENT_TURN step can carry its own."
    }
  }
}