> ## 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. # Update a flow's happy path > Updates the happy path's title, persona, environment, brief or expectations. Omitted fields are left alone; `additionalExpectations` replaces the set wholesale rather than appending. Its persona and environment are what the edge cases inherit, so changing them here changes every edge case that does not name its own. ## OpenAPI ````yaml /api-reference/openapi.documented.json put /v1/customer-flow/{flowId}/happy-path 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 Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Call Analysis - name: Health paths: /v1/customer-flow/{flowId}/happy-path: put: tags: - Customer Flow summary: Update a flow's happy path description: >- Updates the happy path's title, persona, environment, brief or expectations. Omitted fields are left alone; `additionalExpectations` replaces the set wholesale rather than appending. Its persona and environment are what the edge cases inherit, so changing them here changes every edge case that does not name its own. operationId: putV1Customer-flowByFlowIdHappy-path parameters: - in: path name: flowId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateFlowVariantInput' responses: '200': description: The updated happy path content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/FlowVariant' 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 '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.updateHappyPath('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); 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.update_happy_path( flow_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response.data) components: schemas: UpdateFlowVariantInput: type: object properties: title: type: string minLength: 1 environmentId: type: - string - 'null' format: uuid prompt: type: - string - 'null' precededByCustomerFlowId: type: - string - 'null' format: uuid precededByCustomerFlowVariantId: type: - string - 'null' format: uuid personaOverrideId: type: - string - 'null' format: uuid description: >- The persona this runs as. Null on an edge case inherits the happy path's. additionalExpectations: type: array items: $ref: '#/components/schemas/FlowExpectationInput' description: >- Replaces the expectations that apply to this variant on top of the flow's. Omit to leave them alone, send [] to clear. Improv flows only: a scripted variant's expectations come from the agent turns on its path and are rewritten on the next graph edit. description: >- Fields to change on a variant. Omitted fields are left alone. Making a variant the default is a separate operation, since it also demotes the current default. FlowVariant: oneOf: - $ref: '#/components/schemas/ScriptedFlowVariant' - $ref: '#/components/schemas/ImprovFlowVariant' - $ref: '#/components/schemas/VoicemailFlowVariant' discriminator: propertyName: type mapping: SCRIPTED: $ref: '#/components/schemas/ScriptedFlowVariant' IMPROV: $ref: '#/components/schemas/ImprovFlowVariant' VOICEMAIL: $ref: '#/components/schemas/VoicemailFlowVariant' description: One way of running a customer flow. 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 FlowExpectationInput: type: object properties: prompt: type: string minLength: 1 description: What the agent under test is graded against. example: The agent confirmed the new appointment time back to the customer required: - prompt ScriptedFlowVariant: type: object properties: id: type: string format: uuid title: type: string minLength: 1 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 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 gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM 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 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 default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) 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: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - 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 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 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 gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM 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 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 default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) 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: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - 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. required: - id - title - precededByCustomerFlowId - precededByCustomerFlowVariantId - isGenerated - createdAt - updatedAt - personaOverride - environment - additionalExpectations - type 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 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 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 gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM 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 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 default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) 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: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - 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 - DRIVING - OFFICE - THUNDERSTORM default: NONE 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 - 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: '#/components/schemas/FlowStep' mergeIntoNodeIds: type: array items: type: string minLength: 1 type: type: string const: AGENT_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 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 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 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 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 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 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. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````