--- title: "Replace a scripted flow's steps" method: PUT path: "/v1/customer-flow/{flowId}/graph" tags: ["Customer Flow"] --- # Replace a scripted flow's steps `PUT /v1/customer-flow/{flowId}/graph` Replaces a scripted flow's conversation graph with the tree you send. This is a full replace, not a merge: a step you omit is removed. Include `nodeId` on a step to update the existing one, omit it to create a new step. Where two branches rejoin, keep the `mergeIntoNodeIds` references a read gave you. Dropping them un-merges those branches and is refused unless `allowUnmerge` is set. A change to the set of paths re-seeds how the flow runs, which the response reports as `variantsReshaped` along with the resulting happy path and edge cases. ## Path parameters - `flowId` string, uuid, required ## Request body - ReplaceFlowStepsInput - `graph` FlowStep[], required — The complete graph. This replaces the flow's existing steps rather than merging into them. - union — One step in a scripted flow's conversation. `nodeId` is the identity contract: include it to update the existing step, omit it to create a new one. A step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which names steps elsewhere in the same request that this step rejoins. Branches that come back together are represented that way rather than by repeating the shared step, so reading a flow, editing it and writing it back preserves it exactly. A merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in the same request. `ref` is a label you choose, it is request-local, and it is never stored or returned. Put the shared step inline under the first branch that reaches it and point the others at it: a top-level step is a root wired straight from the start of the flow, so a merge target parked there would also be reachable directly. - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'AGENT_TURN', required - `content` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_TURN', required - `content` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_FIRST_MESSAGE', required - `content` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_SILENCE', required - `silenceDurationSeconds` integer, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_DTMF', required - `dtmfDigits` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'VOICEMAIL', required - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'SCENARIO_LINK', required - `linkedCustomerFlowId` string, uuid, nullable - `linkedCustomerFlowVariantId` string, uuid, nullable - `allowUnmerge` boolean — Confirms a write that drops branches which currently rejoin. Only needed when the request omits mergeIntoNodeIds references the flow already had; a faithful round trip never needs it. ## Response `200` The flow graph after the write - object - `data` ReplaceFlowStepsResponse, required - `graph` FlowStep[], required - union — One step in a scripted flow's conversation. `nodeId` is the identity contract: include it to update the existing step, omit it to create a new one. A step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which names steps elsewhere in the same request that this step rejoins. Branches that come back together are represented that way rather than by repeating the shared step, so reading a flow, editing it and writing it back preserves it exactly. A merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in the same request. `ref` is a label you choose, it is request-local, and it is never stored or returned. Put the shared step inline under the first branch that reaches it and point the others at it: a top-level step is a root wired straight from the start of the flow, so a merge target parked there would also be reachable directly. - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'AGENT_TURN', required - `content` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_TURN', required - `content` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_FIRST_MESSAGE', required - `content` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_SILENCE', required - `silenceDurationSeconds` integer, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'CUSTOMER_DTMF', required - `dtmfDigits` string, nullable - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'VOICEMAIL', required - object - `nodeId` string, uuid - `ref` string - `steps` FlowStep[] - `mergeIntoNodeIds` string[] - `type` 'SCENARIO_LINK', required - `linkedCustomerFlowId` string, uuid, nullable - `linkedCustomerFlowVariantId` string, uuid, nullable - `variantsReshaped` boolean, required — True when the write changed the set of paths, so the flow's variants were re-seeded and any variant id you were holding may no longer exist. - `happyPath` union, required — The way a customer flow is meant to go. - ScriptedFlowHappyPath — One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these. - `id` string, uuid, required - `title` string, required - `precededByCustomerFlowId` string, uuid, nullable, required - `precededByCustomerFlowVariantId` string, uuid, nullable, required - `isGenerated` boolean, required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `personaOverride` object, nullable, required — The persona this runs as instead of the happy path's. Null means it inherits. - `id` string, uuid, required — Unique identifier of the persona - `name` string, required — The name the agent will identify as during conversations - `description` string, nullable — Human-readable description of the persona - `language` 'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' | 'HE', required — Primary language ISO 639-1 code for the persona - `secondaryLanguage` 'EN', nullable — Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) - `understoodLanguages` string[], required — Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. - `accent` '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', required — Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants - `age` 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY', required — 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` 'MALE' | 'FEMALE', required — Gender of the persona - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required — Background noise setting - `speechPace` 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST', required — Speech pace of the persona - `speechClarity` 'CLEAR' | 'VAGUE' | 'RAMBLING', required — Speech clarity of the persona - `hasDisfluencies` boolean, required — Whether the persona uses filler words like "um" and "uh" - `baseEmotion` 'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED', required — Base emotional state of the persona - `intentClarity` 'CLEAR' | 'INDIRECT' | 'VAGUE', required — How clearly the persona expresses their intentions - `confirmationStyle` 'EXPLICIT' | 'VAGUE', required — How the persona confirms information - `memoryReliability` 'HIGH' | 'LOW', required — How reliable the persona's memory is - `responseTiming` 'RELAXED' | 'NORMAL' | 'QUICK', required — Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) - `backstoryPrompt` string, nullable — Background story and behavioral patterns for the persona - `idleMessages` string[], nullable, required — Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. - `idleTimeoutSeconds` integer, required — Seconds of silence before the persona sends an idle message - `idleMessageMaxSpokenCount` integer, required — Maximum number of idle messages the persona will send before giving up - `idleMessageResetCountOnUserSpeechEnabled` boolean, required — Whether the idle message counter resets when the agent speaks - `properties` object, required — Additional custom properties about the persona - `createdAt` string, required — Creation timestamp - `updatedAt` string, required — Last update timestamp - `environment` EnvironmentResponse, required — 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. - `id` string, uuid, required - `name` string, required - `description` string, nullable - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `additionalExpectations` FlowExpectation[], required — Graded on top of the flow's own expectations, for this variant only. - `id` string, uuid, required - `prompt` string, required — What the agent under test is graded against. - `type` 'SCRIPTED', required - `steps` FlowStep[], required — The one path through the graph this variant runs, in order. Linear by construction, so these steps never nest. - union — One step in a scripted flow's conversation. `nodeId` is the identity contract: include it to update the existing step, omit it to create a new one. A step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which names steps elsewhere in the same request that this step rejoins. Branches that come back together are represented that way rather than by repeating the shared step, so reading a flow, editing it and writing it back preserves it exactly. A merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in the same request. `ref` is a label you choose, it is request-local, and it is never stored or returned. Put the shared step inline under the first branch that reaches it and point the others at it: a top-level step is a root wired straight from the start of the flow, so a merge target parked there would also be reachable directly. - object - … - object - … - object - … - object - … - object - … - object - … - object - … - ImprovFlowHappyPath — One brief to run an improv flow with. - `id` string, uuid, required - `title` string, required - `precededByCustomerFlowId` string, uuid, nullable, required - `precededByCustomerFlowVariantId` string, uuid, nullable, required - `isGenerated` boolean, required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `personaOverride` object, nullable, required — The persona this runs as instead of the happy path's. Null means it inherits. - `id` string, uuid, required — Unique identifier of the persona - `name` string, required — The name the agent will identify as during conversations - `description` string, nullable — Human-readable description of the persona - `language` 'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' | 'HE', required — Primary language ISO 639-1 code for the persona - `secondaryLanguage` 'EN', nullable — Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) - `understoodLanguages` string[], required — Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. - `accent` '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', required — Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants - `age` 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY', required — 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` 'MALE' | 'FEMALE', required — Gender of the persona - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required — Background noise setting - `speechPace` 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST', required — Speech pace of the persona - `speechClarity` 'CLEAR' | 'VAGUE' | 'RAMBLING', required — Speech clarity of the persona - `hasDisfluencies` boolean, required — Whether the persona uses filler words like "um" and "uh" - `baseEmotion` 'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED', required — Base emotional state of the persona - `intentClarity` 'CLEAR' | 'INDIRECT' | 'VAGUE', required — How clearly the persona expresses their intentions - `confirmationStyle` 'EXPLICIT' | 'VAGUE', required — How the persona confirms information - `memoryReliability` 'HIGH' | 'LOW', required — How reliable the persona's memory is - `responseTiming` 'RELAXED' | 'NORMAL' | 'QUICK', required — Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) - `backstoryPrompt` string, nullable — Background story and behavioral patterns for the persona - `idleMessages` string[], nullable, required — Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. - `idleTimeoutSeconds` integer, required — Seconds of silence before the persona sends an idle message - `idleMessageMaxSpokenCount` integer, required — Maximum number of idle messages the persona will send before giving up - `idleMessageResetCountOnUserSpeechEnabled` boolean, required — Whether the idle message counter resets when the agent speaks - `properties` object, required — Additional custom properties about the persona - `createdAt` string, required — Creation timestamp - `updatedAt` string, required — Last update timestamp - `environment` EnvironmentResponse, required — 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. - `id` string, uuid, required - `name` string, required - `description` string, nullable - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `additionalExpectations` FlowExpectation[], required — Graded on top of the flow's own expectations, for this variant only. - `id` string, uuid, required - `prompt` string, required — What the agent under test is graded against. - `type` 'IMPROV', required - `prompt` string, nullable — The brief the simulated customer improvises from. - VoicemailFlowHappyPath — One voicemail greeting. - `id` string, uuid, required - `title` string, required - `precededByCustomerFlowId` string, uuid, nullable, required - `precededByCustomerFlowVariantId` string, uuid, nullable, required - `isGenerated` boolean, required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `personaOverride` object, nullable, required — The persona this runs as instead of the happy path's. Null means it inherits. - `id` string, uuid, required — Unique identifier of the persona - `name` string, required — The name the agent will identify as during conversations - `description` string, nullable — Human-readable description of the persona - `language` 'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' | 'HE', required — Primary language ISO 639-1 code for the persona - `secondaryLanguage` 'EN', nullable — Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) - `understoodLanguages` string[], required — Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. - `accent` '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', required — Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants - `age` 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY', required — 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` 'MALE' | 'FEMALE', required — Gender of the persona - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required — Background noise setting - `speechPace` 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST', required — Speech pace of the persona - `speechClarity` 'CLEAR' | 'VAGUE' | 'RAMBLING', required — Speech clarity of the persona - `hasDisfluencies` boolean, required — Whether the persona uses filler words like "um" and "uh" - `baseEmotion` 'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED', required — Base emotional state of the persona - `intentClarity` 'CLEAR' | 'INDIRECT' | 'VAGUE', required — How clearly the persona expresses their intentions - `confirmationStyle` 'EXPLICIT' | 'VAGUE', required — How the persona confirms information - `memoryReliability` 'HIGH' | 'LOW', required — How reliable the persona's memory is - `responseTiming` 'RELAXED' | 'NORMAL' | 'QUICK', required — Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) - `backstoryPrompt` string, nullable — Background story and behavioral patterns for the persona - `idleMessages` string[], nullable, required — Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. - `idleTimeoutSeconds` integer, required — Seconds of silence before the persona sends an idle message - `idleMessageMaxSpokenCount` integer, required — Maximum number of idle messages the persona will send before giving up - `idleMessageResetCountOnUserSpeechEnabled` boolean, required — Whether the idle message counter resets when the agent speaks - `properties` object, required — Additional custom properties about the persona - `createdAt` string, required — Creation timestamp - `updatedAt` string, required — Last update timestamp - `environment` EnvironmentResponse, required — 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. - `id` string, uuid, required - `name` string, required - `description` string, nullable - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `additionalExpectations` FlowExpectation[], required — Graded on top of the flow's own expectations, for this variant only. - `id` string, uuid, required - `prompt` string, required — What the agent under test is graded against. - `type` 'VOICEMAIL', required - `edgeCases` FlowVariant[], required — The edge cases after the write. - union — One way of running a customer flow. - ScriptedFlowVariant — One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these. - `id` string, uuid, required - `title` string, required - `precededByCustomerFlowId` string, uuid, nullable, required - `precededByCustomerFlowVariantId` string, uuid, nullable, required - `isGenerated` boolean, required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `personaOverride` object, nullable, required — The persona this runs as instead of the happy path's. Null means it inherits. - `id` string, uuid, required — Unique identifier of the persona - `name` string, required — The name the agent will identify as during conversations - `description` string, nullable — Human-readable description of the persona - `language` 'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' | 'HE', required — Primary language ISO 639-1 code for the persona - `secondaryLanguage` 'EN', nullable — Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) - `understoodLanguages` string[], required — Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. - `accent` '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', required — Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants - `age` 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY', required — 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` 'MALE' | 'FEMALE', required — Gender of the persona - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required — Background noise setting - `speechPace` 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST', required — Speech pace of the persona - `speechClarity` 'CLEAR' | 'VAGUE' | 'RAMBLING', required — Speech clarity of the persona - `hasDisfluencies` boolean, required — Whether the persona uses filler words like "um" and "uh" - `baseEmotion` 'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED', required — Base emotional state of the persona - `intentClarity` 'CLEAR' | 'INDIRECT' | 'VAGUE', required — How clearly the persona expresses their intentions - `confirmationStyle` 'EXPLICIT' | 'VAGUE', required — How the persona confirms information - `memoryReliability` 'HIGH' | 'LOW', required — How reliable the persona's memory is - `responseTiming` 'RELAXED' | 'NORMAL' | 'QUICK', required — Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) - `backstoryPrompt` string, nullable — Background story and behavioral patterns for the persona - `idleMessages` string[], nullable, required — Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. - `idleTimeoutSeconds` integer, required — Seconds of silence before the persona sends an idle message - `idleMessageMaxSpokenCount` integer, required — Maximum number of idle messages the persona will send before giving up - `idleMessageResetCountOnUserSpeechEnabled` boolean, required — Whether the idle message counter resets when the agent speaks - `properties` object, required — Additional custom properties about the persona - `createdAt` string, required — Creation timestamp - `updatedAt` string, required — Last update timestamp - `environment` EnvironmentResponse, required — 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. - `id` string, uuid, required - `name` string, required - `description` string, nullable - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `additionalExpectations` FlowExpectation[], required — Graded on top of the flow's own expectations, for this variant only. - `id` string, uuid, required - `prompt` string, required — What the agent under test is graded against. - `type` 'SCRIPTED', required - `steps` FlowStep[], required — The one path through the graph this variant runs, in order. Linear by construction, so these steps never nest. - union — One step in a scripted flow's conversation. `nodeId` is the identity contract: include it to update the existing step, omit it to create a new one. A step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which names steps elsewhere in the same request that this step rejoins. Branches that come back together are represented that way rather than by repeating the shared step, so reading a flow, editing it and writing it back preserves it exactly. A merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in the same request. `ref` is a label you choose, it is request-local, and it is never stored or returned. Put the shared step inline under the first branch that reaches it and point the others at it: a top-level step is a root wired straight from the start of the flow, so a merge target parked there would also be reachable directly. - … - ImprovFlowVariant — One brief to run an improv flow with. - `id` string, uuid, required - `title` string, required - `precededByCustomerFlowId` string, uuid, nullable, required - `precededByCustomerFlowVariantId` string, uuid, nullable, required - `isGenerated` boolean, required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `personaOverride` object, nullable, required — The persona this runs as instead of the happy path's. Null means it inherits. - `id` string, uuid, required — Unique identifier of the persona - `name` string, required — The name the agent will identify as during conversations - `description` string, nullable — Human-readable description of the persona - `language` 'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' | 'HE', required — Primary language ISO 639-1 code for the persona - `secondaryLanguage` 'EN', nullable — Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) - `understoodLanguages` string[], required — Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. - `accent` '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', required — Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants - `age` 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY', required — 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` 'MALE' | 'FEMALE', required — Gender of the persona - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required — Background noise setting - `speechPace` 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST', required — Speech pace of the persona - `speechClarity` 'CLEAR' | 'VAGUE' | 'RAMBLING', required — Speech clarity of the persona - `hasDisfluencies` boolean, required — Whether the persona uses filler words like "um" and "uh" - `baseEmotion` 'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED', required — Base emotional state of the persona - `intentClarity` 'CLEAR' | 'INDIRECT' | 'VAGUE', required — How clearly the persona expresses their intentions - `confirmationStyle` 'EXPLICIT' | 'VAGUE', required — How the persona confirms information - `memoryReliability` 'HIGH' | 'LOW', required — How reliable the persona's memory is - `responseTiming` 'RELAXED' | 'NORMAL' | 'QUICK', required — Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) - `backstoryPrompt` string, nullable — Background story and behavioral patterns for the persona - `idleMessages` string[], nullable, required — Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. - `idleTimeoutSeconds` integer, required — Seconds of silence before the persona sends an idle message - `idleMessageMaxSpokenCount` integer, required — Maximum number of idle messages the persona will send before giving up - `idleMessageResetCountOnUserSpeechEnabled` boolean, required — Whether the idle message counter resets when the agent speaks - `properties` object, required — Additional custom properties about the persona - `createdAt` string, required — Creation timestamp - `updatedAt` string, required — Last update timestamp - `environment` EnvironmentResponse, required — 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. - `id` string, uuid, required - `name` string, required - `description` string, nullable - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `additionalExpectations` FlowExpectation[], required — Graded on top of the flow's own expectations, for this variant only. - `id` string, uuid, required - `prompt` string, required — What the agent under test is graded against. - `type` 'IMPROV', required - `prompt` string, nullable — The brief the simulated customer improvises from. - VoicemailFlowVariant — One voicemail greeting. - `id` string, uuid, required - `title` string, required - `precededByCustomerFlowId` string, uuid, nullable, required - `precededByCustomerFlowVariantId` string, uuid, nullable, required - `isGenerated` boolean, required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `personaOverride` object, nullable, required — The persona this runs as instead of the happy path's. Null means it inherits. - `id` string, uuid, required — Unique identifier of the persona - `name` string, required — The name the agent will identify as during conversations - `description` string, nullable — Human-readable description of the persona - `language` 'EN' | 'ES' | 'DE' | 'HI' | 'FR' | 'NL' | 'AR' | 'EL' | 'IT' | 'ID' | 'TH' | 'JA' | 'TL' | 'MS' | 'ZH' | 'TR' | 'PT' | 'HE', required — Primary language ISO 639-1 code for the persona - `secondaryLanguage` 'EN', nullable — Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) - `understoodLanguages` string[], required — Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. - `accent` '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', required — Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants - `age` 'CHILD' | 'TEENAGER' | 'ADULT' | 'ELDERLY', required — 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` 'MALE' | 'FEMALE', required — Gender of the persona - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required — Background noise setting - `speechPace` 'SUPER_SLOW' | 'SLOW' | 'NORMAL' | 'FAST' | 'SUPER_FAST', required — Speech pace of the persona - `speechClarity` 'CLEAR' | 'VAGUE' | 'RAMBLING', required — Speech clarity of the persona - `hasDisfluencies` boolean, required — Whether the persona uses filler words like "um" and "uh" - `baseEmotion` 'NEUTRAL' | 'CHEERFUL' | 'CONFUSED' | 'FRUSTRATED' | 'SKEPTICAL' | 'RUSHED' | 'DISTRACTED', required — Base emotional state of the persona - `intentClarity` 'CLEAR' | 'INDIRECT' | 'VAGUE', required — How clearly the persona expresses their intentions - `confirmationStyle` 'EXPLICIT' | 'VAGUE', required — How the persona confirms information - `memoryReliability` 'HIGH' | 'LOW', required — How reliable the persona's memory is - `responseTiming` 'RELAXED' | 'NORMAL' | 'QUICK', required — Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) - `backstoryPrompt` string, nullable — Background story and behavioral patterns for the persona - `idleMessages` string[], nullable, required — Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. - `idleTimeoutSeconds` integer, required — Seconds of silence before the persona sends an idle message - `idleMessageMaxSpokenCount` integer, required — Maximum number of idle messages the persona will send before giving up - `idleMessageResetCountOnUserSpeechEnabled` boolean, required — Whether the idle message counter resets when the agent speaks - `properties` object, required — Additional custom properties about the persona - `createdAt` string, required — Creation timestamp - `updatedAt` string, required — Last update timestamp - `environment` EnvironmentResponse, required — 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. - `id` string, uuid, required - `name` string, required - `description` string, nullable - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'DRIVING' | 'OFFICE' | 'THUNDERSTORM', required - `createdAt` string, required — Creation timestamp in ISO 8601 format - `updatedAt` string, required — Last update timestamp in ISO 8601 format - `additionalExpectations` FlowExpectation[], required — Graded on top of the flow's own expectations, for this variant only. - `id` string, uuid, required - `prompt` string, required — What the agent under test is graded against. - `type` 'VOICEMAIL', required - `warnings` string[], required ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — The write drops branches that currently rejoin. Set allowUnmerge to confirm. - `429` — Too Many Requests - `500` — Internal Server Error ## Changes - **2026-08-26** `b4a59c7057ca` — 1 breaking, 11 info - the response's body type/format changed from ``/`` to `object`/`` for status `409` - added the optional property `details` to the response with the `409` status - added the optional property `param` to the response with the `409` status - added the required property `code` to the response with the `409` status - …8 more - **2026-08-17** `887b091b3d81` — 1 info - endpoint added [Change history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/customer-flow/:flowId/graph/put.md) --- [API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) · [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/revisions/1d61b68e9429/schema)