Roark · Schema
FlowVariant
One way of running a customer flow.
CompanyVoice AITestingEvaluationBenchmarking
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/roark/json-schema/roark-flow-variant-schema.json",
"title": "FlowVariant",
"description": "One way of running a customer flow.",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/roark-customer-flow-edge-case-api-openapi.yml#/components/schemas/FlowVariant",
"oneOf": [
{
"$ref": "#/$defs/ScriptedFlowVariant"
},
{
"$ref": "#/$defs/ImprovFlowVariant"
},
{
"$ref": "#/$defs/VoicemailFlowVariant"
}
],
"$defs": {
"EnvironmentResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"minLength": 1
},
"description": {
"type": [
"string",
"null"
]
},
"backgroundNoise": {
"type": "string",
"enum": [
"NONE",
"AIRPORT",
"CHILDREN_PLAYING",
"CITY",
"COFFEE_SHOP",
"CONSTRUCTION",
"CRYING_BABY",
"DRIVING",
"LIBRARY",
"OFFICE",
"THUNDERSTORM",
"TRAIN"
],
"default": "NONE"
},
"backgroundNoiseVolume": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.1
},
"createdAt": {
"type": "string",
"description": "Creation timestamp in ISO 8601 format"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp in ISO 8601 format"
}
},
"required": [
"id",
"name",
"backgroundNoise",
"backgroundNoiseVolume",
"createdAt",
"updatedAt"
],
"description": "A simulation environment: the ambient conditions a customer flow variant runs under. The list includes both your own and the ones Roark curates for every project."
},
"FlowExpectation": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"prompt": {
"type": "string",
"description": "What the agent under test is graded against."
}
},
"required": [
"id",
"prompt"
],
"description": "One thing the agent under test is graded against."
},
"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."
},
"ImprovFlowVariant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"minLength": 1
},
"systemKey": {
"type": [
"string",
"null"
]
},
"precededByCustomerFlowId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"precededByCustomerFlowVariantId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"isGenerated": {
"type": "boolean",
"default": false
},
"includeFlowExpectations": {
"type": "boolean",
"description": "Whether this variant is graded on the flow's agentExpectations as well as its additionalExpectations. False grades it on its additionalExpectations only. Always true on the happy path."
},
"createdAt": {
"type": "string",
"description": "Creation timestamp in ISO 8601 format"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp in ISO 8601 format"
},
"personaOverride": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the persona"
},
"name": {
"type": "string",
"description": "The name the agent will identify as during conversations"
},
"displayName": {
"type": [
"string",
"null"
],
"description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself."
},
"description": {
"type": [
"string",
"null"
],
"description": "Human-readable description of the persona"
},
"language": {
"type": "string",
"enum": [
"EN",
"ES",
"DE",
"HI",
"FR",
"NL",
"AR",
"EL",
"IT",
"ID",
"TH",
"JA",
"TL",
"MS",
"ZH",
"TR",
"PT",
"HE"
],
"description": "Primary language ISO 639-1 code for the persona"
},
"secondaryLanguage": {
"type": [
"string",
"null"
],
"enum": [
"EN"
],
"description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)"
},
"understoodLanguages": {
"type": "array",
"items": {
"type": "string",
"enum": [
"EN",
"ES",
"DE",
"HI",
"FR",
"NL",
"AR",
"EL",
"IT",
"ID",
"TH",
"JA",
"TL",
"MS",
"ZH",
"TR",
"PT",
"HE"
]
},
"minItems": 1,
"description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support."
},
"accent": {
"type": "string",
"enum": [
"US",
"US_X_SOUTH",
"GB",
"ES",
"DE",
"IN",
"FR",
"NL",
"SA",
"GR",
"AU",
"IT",
"ID",
"TH",
"JP",
"NZ",
"PH",
"SG",
"MY",
"HK",
"TR",
"PT",
"IL"
],
"description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants"
},
"age": {
"type": "string",
"enum": [
"CHILD",
"TEENAGER",
"ADULT",
"ELDERLY"
],
"default": "ADULT",
"description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports."
},
"gender": {
"type": "string",
"enum": [
"MALE",
"FEMALE"
],
"description": "Gender of the persona"
},
"backgroundNoise": {
"type": "string",
"enum": [
"NONE",
"AIRPORT",
"CHILDREN_PLAYING",
"CITY",
"COFFEE_SHOP",
"CONSTRUCTION",
"CRYING_BABY",
"DRIVING",
"LIBRARY",
"OFFICE",
"THUNDERSTORM",
"TRAIN"
],
"default": "NONE",
"description": "Background noise setting"
},
"speechPace": {
"type": "string",
"enum": [
"SUPER_SLOW",
"SLOW",
"NORMAL",
"FAST",
"SUPER_FAST"
],
"default": "NORMAL",
"description": "Speech pace of the persona"
},
"speechClarity": {
"type": "string",
"enum": [
"CLEAR",
"VAGUE",
"RAMBLING"
],
"default": "CLEAR",
"description": "Speech clarity of the persona"
},
"hasDisfluencies": {
"type": "boolean",
"default": false,
"description": "Whether the persona uses filler words like \"um\" and \"uh\""
},
"baseEmotion": {
"type": "string",
"enum": [
"NEUTRAL",
"CHEERFUL",
"CONFUSED",
"FRUSTRATED",
"SKEPTICAL",
"RUSHED",
"DISTRACTED",
"ANGRY",
"ANXIOUS",
"SAD"
],
"default": "NEUTRAL",
"description": "Base emotional state of the persona"
},
"intentClarity": {
"type": "string",
"enum": [
"CLEAR",
"INDIRECT",
"VAGUE"
],
"default": "CLEAR",
"description": "How clearly the persona expresses their intentions"
},
"confirmationStyle": {
"type": "string",
"enum": [
"EXPLICIT",
"VAGUE"
],
"default": "EXPLICIT",
"description": "How the persona confirms information"
},
"memoryReliability": {
"type": "string",
"enum": [
"HIGH",
"LOW"
],
"default": "HIGH",
"description": "How reliable the persona's memory is"
},
"responseTiming": {
"type": "string",
"enum": [
"RELAXED",
"NORMAL",
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://artifacts.apis.io/roark/json-schema/roark-flow-variant-schema.json
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/roark-flow-variant"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.