> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace a scripted flow's steps > 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. ## OpenAPI ````yaml /api-reference/openapi.documented.json put /v1/customer-flow/{flowId}/graph openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/customer-flow/{flowId}/graph: put: tags: - Customer Flow summary: Replace a scripted flow's steps description: >- 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. operationId: putV1Customer-flowByFlowIdGraph parameters: - in: path name: flowId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/ReplaceFlowStepsInput' responses: '200': description: The flow graph after the write content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ReplaceFlowStepsResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: >- The write drops branches that currently rejoin. Set allowUnmerge to confirm. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.customerFlow.replaceGraph('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { graph: [{ type: 'AGENT_TURN' }], }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.customer_flow.replace_graph( flow_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", graph=[{ "type": "AGENT_TURN" }], ) print(response.data) components: schemas: ReplaceFlowStepsInput: type: object properties: graph: type: array items: $ref: '#/components/schemas/FlowStep' minItems: 1 description: >- The complete graph. This replaces the flow's existing steps rather than merging into them. allowUnmerge: type: boolean description: >- 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. required: - graph ReplaceFlowStepsResponse: type: object properties: graph: type: array items: $ref: '#/components/schemas/FlowStep' variantsReshaped: type: boolean description: >- 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: oneOf: - $ref: '#/components/schemas/FlowHappyPath' - type: 'null' description: The happy path after the write. edgeCases: type: array items: $ref: '#/components/schemas/FlowVariant' description: The edge cases after the write. warnings: type: array items: type: string required: - graph - variantsReshaped - happyPath - edgeCases - warnings ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message FlowStep: oneOf: - type: object properties: nodeId: type: string format: uuid ref: type: string minLength: 1 maxLength: 64 steps: type: array items: $ref: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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. `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. A `CUSTOMER_TURN` describes what the simulated customer says and the persona phrases it; a `CUSTOMER_VERBATIM_TURN` is said word for word, and one placed as a top-level step opens the call the moment it connects, before the agent speaks. `CUSTOMER_FIRST_MESSAGE` is the retired name for that opening case: still accepted, stored and returned as `CUSTOMER_VERBATIM_TURN`. The two DTMF types are mirror images and both require `dtmfDigits`. `CUSTOMER_DTMF` is keys the simulated caller presses while navigating your agent. `AGENT_DTMF` is keys your agent under test is expected to press while navigating a menu the simulation is playing, so its digits are an assertion the run is graded against rather than an instruction, and it counts as an agent turn for role alternation. A `CUSTOMER_HANDOFF` hands the phone to another persona (`handoffPersonaId`), or back to the flow's own persona when it is null. The steps after it are spoken by whoever holds the phone. It sits between turns like a silence, so it may follow either side. In a STRICT flow an `AGENT_TURN` may carry its own `offScriptPolicy`, which replaces the flow-level one at that step. Omit it (or send null) to follow the flow's policy. Use it where one missed step makes the rest of the call meaningless: an authentication menu, say, with `then: HANG_UP_INVALIDATE`. Any step may set `stage`, the named phase of the flow it belongs to: the IVR, the login, the scenario itself. Steps in one stage are drawn as a group in the editor, and the name is yours: the reports say it back to you. The stage does not have to exist first, it is created the first time a step names it, and a name already in the project is matched ignoring case. A stage with `required: true` is a gate. A run that ends without getting PAST it never reached what was being measured, so it stays in the report, labelled with the stage it never completed and the one it stopped in, and is left out of the run score and the success-criteria verdict: an agent that never clears the IVR does not fail every check in a scenario it never started. `required` belongs to the stage rather than to the step, so a read returns it on every step in that stage, and a write that sets it on any one of them marks the whole stage. A flow that requires no stage is scored exactly as before. A stage with `analyze: false` is not measured. Its turns are kept out of the core call metrics (talk time, speech pace, turn and response timings), which is what an IVR usually wants alongside `required: true`: the run has to get through the menu, but how the agent sounded reading it is not what is being tested. Coverage is being extended package by package, so the judged metrics (quality, compliance, repetition, escalation, tone) still read the whole call for now. Nothing is cut and nothing is re-timed, so a turn at 4:10 is still at 4:10 with an earlier stage excluded, and rate metrics divide by the part of the call that was measured rather than by the whole of it. Defaults to true, belongs to the stage the same way `required` does, and turning it off on any one step turns it off for the stage. FlowHappyPath: oneOf: - $ref: '#/components/schemas/ScriptedFlowHappyPath' - $ref: '#/components/schemas/ImprovFlowHappyPath' - $ref: '#/components/schemas/VoicemailFlowHappyPath' discriminator: propertyName: type mapping: SCRIPTED: '#/components/schemas/ScriptedFlowHappyPath' IMPROV: '#/components/schemas/ImprovFlowHappyPath' VOICEMAIL: '#/components/schemas/VoicemailFlowHappyPath' description: The way a customer flow is meant to go. FlowVariant: oneOf: - $ref: '#/components/schemas/ScriptedFlowVariant' - $ref: '#/components/schemas/ImprovFlowVariant' - $ref: '#/components/schemas/VoicemailFlowVariant' discriminator: propertyName: type mapping: SCRIPTED: '#/components/schemas/ScriptedFlowVariant' IMPROV: '#/components/schemas/ImprovFlowVariant' VOICEMAIL: '#/components/schemas/VoicemailFlowVariant' description: One way of running a customer flow. ScriptedFlowHappyPath: allOf: - $ref: '#/components/schemas/ScriptedFlowVariant' title: Scripted description: >- One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these. ImprovFlowHappyPath: allOf: - $ref: '#/components/schemas/ImprovFlowVariant' title: Improv description: One brief to run an improv flow with. VoicemailFlowHappyPath: allOf: - $ref: '#/components/schemas/VoicemailFlowVariant' title: Voicemail description: One voicemail greeting. ScriptedFlowVariant: 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 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 - QUICK - BARGE_IN default: NORMAL description: >- Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`. interruption: type: string enum: - 'OFF' - BACKCHANNEL - OCCASIONAL - HEAVY default: 'OFF' description: >- How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises ("mm-hm") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments. backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: {} default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer phoneNumber: type: string description: >- The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only. example: '+19312830919' createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - age - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - interruption - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The persona this runs as instead of the happy path's. Null means it inherits. environment: oneOf: - $ref: '#/components/schemas/EnvironmentResponse' - type: 'null' description: >- The conditions this runs under. Null means it inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' description: Graded on top of the flow's own expectations, for this variant only. type: type: string const: SCRIPTED steps: type: array items: $ref: '#/components/schemas/FlowStep' description: >- The one path through the graph this variant runs, in order. Linear by construction, so these steps never nest. required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type - steps title: Scripted description: >- One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these. 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 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 - QUICK - BARGE_IN default: NORMAL description: >- Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`. interruption: type: string enum: - 'OFF' - BACKCHANNEL - OCCASIONAL - HEAVY default: 'OFF' description: >- How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises ("mm-hm") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments. backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: {} default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer phoneNumber: type: string description: >- The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only. example: '+19312830919' createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - age - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - interruption - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The persona this runs as instead of the happy path's. Null means it inherits. environment: oneOf: - $ref: '#/components/schemas/EnvironmentResponse' - type: 'null' description: >- The conditions this runs under. Null means it inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' description: Graded on top of the flow's own expectations, for this variant only. type: type: string const: IMPROV prompt: type: - string - 'null' description: >- The brief the simulated customer improvises from. A `@{persona:}` mention hands the phone to that persona mid-call; the sentences around the mention say when. handoffPersonas: type: array items: type: object 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 - QUICK - BARGE_IN default: NORMAL description: >- Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`. interruption: type: string enum: - 'OFF' - BACKCHANNEL - OCCASIONAL - HEAVY default: 'OFF' description: >- How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises ("mm-hm") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments. backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: {} default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer phoneNumber: type: string description: >- The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only. example: '+19312830919' createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - age - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - interruption - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The personas this brief hands the phone to, in order of first mention. Empty when the brief inherits the happy path's: read the happy path's list. required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type - handoffPersonas title: Improv description: One brief to run an improv flow with. VoicemailFlowVariant: 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 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 - QUICK - BARGE_IN default: NORMAL description: >- Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`. interruption: type: string enum: - 'OFF' - BACKCHANNEL - OCCASIONAL - HEAVY default: 'OFF' description: >- How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises ("mm-hm") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments. backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: {} default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer phoneNumber: type: string description: >- The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only. example: '+19312830919' createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - age - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - interruption - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt description: >- The persona this runs as instead of the happy path's. Null means it inherits. environment: oneOf: - $ref: '#/components/schemas/EnvironmentResponse' - type: 'null' description: >- The conditions this runs under. Null means it inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectation' description: Graded on top of the flow's own expectations, for this variant only. type: type: string const: VOICEMAIL required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type title: Voicemail description: One voicemail greeting. 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. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.