> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Agent Draft

> Returns your own draft of the agent: its summary, full config and test values. 404 `MemberDraftNotFound` (reason `NO_DRAFT`) when you have none: then the agent is as in its newest version. With `revision`, returns the config at that draft revision or version instead. How versions work: every agent edit goes into **your own draft** (Update Voice Agent and Save Agent Draft write to it). A draft becomes a **version** when a project member publishes it in the dashboard; API keys can propose a draft but not publish. 



## OpenAPI

````yaml /api-reference/openapi.json get /v2/voice-agents/{voiceAgentId}/draft
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v2/voice-agents/{voiceAgentId}/draft:
    get:
      summary: Get your agent draft
      description: >-
        Returns your own draft of the agent: its summary, full config and test
        values. 404 `MemberDraftNotFound` (reason `NO_DRAFT`) when you have
        none: then the agent is as in its newest version. With `revision`,
        returns the config at that draft revision or version instead. How
        versions work: every agent edit goes into **your own draft** (Update
        Voice Agent and Save Agent Draft write to it). A draft becomes a
        **version** when a project member publishes it in the dashboard; API
        keys can propose a draft but not publish. 
      parameters:
        - in: path
          name: voiceAgentId
          required: true
          description: ID of the voice agent.
          schema:
            type: string
            format: uuid
            example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
        - in: query
          name: revision
          required: false
          description: 'A draft revision or version ID: return the config at that point.'
          schema:
            type: string
            format: uuid
            example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    oneOf:
                      - $ref: '#/components/schemas/AgentDraft'
                        title: Your draft
                      - oneOf:
                          - type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
                              type:
                                type: string
                                enum:
                                  - Single Prompt
                                  - Flow Agent
                                  - Transcription Agent
                                example: Flow Agent
                              name:
                                type: string
                                example: My Flow Agent
                              conversation:
                                type: object
                                properties:
                                  greetingMessage:
                                    type: string
                                    example: Hello, how can I help you today?
                                  greetingMessageType:
                                    type: string
                                    example: STATIC
                                    nullable: true
                                    enum:
                                      - STATIC
                                      - PROMPT
                                  preamble:
                                    type: string
                                    example: >-
                                      You are a helpful assistant that will
                                      answer users questions.
                                  pokeMessages:
                                    type: array
                                    items:
                                      type: string
                                    example:
                                      - Are you still there?
                                      - >-
                                        Take your time, I'm here when you're
                                        ready.
                                  params:
                                    type: object
                                    additionalProperties:
                                      type: string
                                    example:
                                      customer_name: Sara
                                      order_number: '48213'
                                  alignment:
                                    type: object
                                    properties:
                                      greetingMessage:
                                        type: string
                                        example: ltr
                                      preamble:
                                        type: string
                                        example: ltr
                              voice:
                                type: object
                                properties:
                                  voiceId:
                                    type: string
                                    example: voice-123
                                    nullable: true
                                  voiceRecordId:
                                    type: string
                                    format: uuid
                                    example: 2e77fa73-180e-4b96-80c6-e87363bed3e4
                                    nullable: true
                                  voiceRecord:
                                    type: object
                                    nullable: true
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                        example: voice-record-123
                                      name:
                                        type: string
                                        example: English Voice
                                      provider:
                                        type: string
                                        example: elevenlabs
                                      ttsParams:
                                        type: object
                                        properties:
                                          voiceId:
                                            type: string
                                            example: voice-123
                                          dialect:
                                            type: string
                                            example: PLS
                                          language:
                                            type: string
                                            example: ar
                                      language:
                                        type: string
                                        example: en
                                  lang:
                                    type: string
                                    enum:
                                      - ar
                                      - en
                                    example: en
                                  config:
                                    type: object
                                    properties:
                                      expressiveness:
                                        type: number
                                        minimum: 0
                                        maximum: 2
                                        example: 1
                                        default: 1
                                        deprecated: true
                                        description: >-
                                          No longer changes how calls sound: see
                                          `casualMode` and `autoEmotion`.
                                      preferredSttModel:
                                        type: string
                                        enum:
                                          - Hamsa-STT-S4
                                          - Hamsa-STT-S3
                                          - Hamsa-STT-English
                                        example: Hamsa-STT-S4
                                        default: Hamsa-STT-S4
                                      casualMode:
                                        type: boolean
                                        example: false
                                        description: >-
                                          Casual mode. `false` for an agent that
                                          never set it.
                                      autoEmotion:
                                        type: boolean
                                        example: true
                                        description: >-
                                          Auto Emotion. `false` for an agent that
                                          never set it.
                                      useReferenceAudio:
                                        type: boolean
                                        example: true
                                        description: >-
                                          Use reference audio. `true` for an agent
                                          that never set it.
                              llm:
                                type: object
                                properties:
                                  provider:
                                    type: string
                                    example: Gemini
                                  model:
                                    type: string
                                    example: gemini-3.5-flash-lite
                                  temperature:
                                    type: number
                                    example: 0.2
                                  baseUrl:
                                    type: string
                                    nullable: true
                                    example: null
                                  apiKey:
                                    type: string
                                    example: '{{secrets.OPENAI_KEY}}'
                                    description: >-
                                      Only when the stored key is exactly one
                                      `{{secrets.NAME}}` reference. Left out
                                      when a raw key is stored: a raw key is
                                      never returned.
                                  reasoningEffort:
                                    type: string
                                    example: null
                                    nullable: true
                                    maxLength: 50
                                    description: >-
                                      Custom provider only (ignored for others).
                                      Free text, trimmed; blank or null clears
                                      it.
                                  hasApiKey:
                                    type: boolean
                                    example: true
                                    description: >-
                                      Whether a key or secret reference is
                                      stored.
                                  apiKeyLast4:
                                    type: string
                                    nullable: true
                                    example: '7890'
                                    description: >-
                                      The last four characters of a stored raw
                                      key of 16 characters or more that holds no
                                      `{{`; `null` otherwise, including for a
                                      secret reference.
                              callSettings:
                                type: object
                                properties:
                                  noiseCancellation:
                                    type: string
                                    example: disabled
                                  cancelNoisePer:
                                    type: string
                                    nullable: true
                                    example: conversation
                                  interrupt:
                                    type: boolean
                                    example: true
                                  responseDelay:
                                    type: number
                                    example: 400
                                  userInactivityTimeout:
                                    type: number
                                    example: 15
                                  maxCallDuration:
                                    type: number
                                    example: 300
                                  silenceThreshold:
                                    type: number
                                    example: 800
                                  backgroundNoise:
                                    type: boolean
                                    example: false
                                  thinkingVoice:
                                    type: boolean
                                    example: false
                                  speakerIdentification:
                                    type: boolean
                                    example: false
                                  agenticRag:
                                    type: boolean
                                    example: false
                                  genderDetection:
                                    type: boolean
                                    example: false
                                  smartCallEnd:
                                    type: boolean
                                    example: false
                                  languageDialectSwitcher:
                                    type: boolean
                                    example: false
                                  waitForUserToSpeakFirst:
                                    type: integer
                                    enum:
                                      - 0
                                      - 1
                                      - 2
                                    default: 0
                                    example: 0
                                  minInterruptionDuration:
                                    type: number
                                    example: 0.5
                                    minimum: 0
                                    maximum: 1.5
                                  vadActivationThreshold:
                                    type: number
                                    example: 0.5
                                    minimum: 0.2
                                    maximum: 0.9
                                  enableAutoGainControl:
                                    type: boolean
                                    example: false
                                  sendDenoisedToStt:
                                    type: boolean
                                    example: false
                                  promptEnhancer:
                                    type: string
                                    enum:
                                      - disabled
                                      - basic
                                      - advanced
                                    example: basic
                                    default: basic
                                  enableEnhancedTurnTaking:
                                    type: boolean
                                    example: false
                                    default: false
                                  smartCallEndPrompt:
                                    type: string
                                    example: >-
                                      Terminate the call when: (1) all customer
                                      inquiries have been resolved, (2) the
                                      conversation has reached a natural
                                      conclusion, (3) the customer's goal has
                                      been achieved, or (4) further conversation
                                      would be unproductive. Use this tool only
                                      when you've achieved the primary objective
                                      of the call.
                                    nullable: true
                                  timezone:
                                    type: string
                                    example: Asia/Amman
                                    nullable: true
                                    description: >-
                                      IANA time zone name the agent uses to
                                      resolve local date/time during
                                      conversations.
                                  maxCallDurationBehavior:
                                    type: object
                                    nullable: true
                                    description: >-
                                      What happens when the call reaches
                                      maxCallDuration. Null or absent = end the
                                      call (default). With 'transfer_call',
                                      `transfer` is required and has the same
                                      shape as a flow Transfer call step.
                                    properties:
                                      action:
                                        type: string
                                        enum:
                                          - end_call
                                          - transfer_call
                                        example: transfer_call
                                      message:
                                        type: string
                                        maxLength: 2000
                                        nullable: true
                                        example: >-
                                          We have reached the time limit, let me
                                          transfer you to {{agent_name}}.
                                        description: >-
                                          What the agent says before ending or
                                          transferring, or with `messageType`
                                          `prompt`, the instruction it follows.
                                          May contain {{variables}}.
                                      messageType:
                                        type: string
                                        enum:
                                          - static
                                          - prompt
                                        default: static
                                        description: >-
                                          `static` says `message` as written.
                                          `prompt` gives it to the agent as an
                                          instruction, and it writes what to say;
                                          allowed only with `transfer_call`.
                                          Ending the call is always `static`.
                                      transfer:
                                        type: object
                                        nullable: true
                                        description: >-
                                          Required when action is 'transfer_call';
                                          ignored otherwise.
                                        properties:
                                          phoneNumberType:
                                            type: string
                                            enum:
                                              - e164
                                              - variable
                                            example: e164
                                          phoneNumber:
                                            type: string
                                            example: '+962790000000'
                                            description: >-
                                              E.164 number when phoneNumberType is
                                              e164, a {{variable}} reference when
                                              variable.
                                          transferType:
                                            type: string
                                            enum:
                                              - cold
                                            default: cold
                                          sipHeaders:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                id:
                                                  type: string
                                                name:
                                                  type: string
                                                value:
                                                  type: string
                                  contextManager:
                                    type: object
                                    nullable: true
                                    description: >-
                                      Smart context manager switch. Null or
                                      absent = the runtime default.
                                    properties:
                                      mode:
                                        type: string
                                        enum:
                                          - active
                                          - 'off'
                                        example: active
                                  onHoldMusicId:
                                    type: string
                                    format: uuid
                                    example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                                    nullable: true
                                    description: >-
                                      ID of the on-hold music track (system or
                                      project-owned) played while the caller
                                      waits on hold.
                                  ambientSoundId:
                                    type: string
                                    format: uuid
                                    example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                                    nullable: true
                                    description: >-
                                      ID of the ambient sound track (system or
                                      project-owned) played in the background
                                      during the call.
                                  onHoldMusic:
                                    type: object
                                    nullable: true
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                        example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                                      name:
                                        type: string
                                        example: Default
                                      url:
                                        type: string
                                        example: >-
                                          https://cdn.tryhamsa.com/audio-assets/default.mp3?Signature=...
                                        description: Signed playable URL for the track.
                                      duration:
                                        type: number
                                        example: 32.5
                                        nullable: true
                                        description: Track duration in seconds.
                                    description: >-
                                      The selected on-hold music track with a
                                      signed playable URL, falling back to the
                                      system "Default" track when nothing is
                                      selected. Only populated on the get-by-id
                                      endpoints.
                                  ambientSound:
                                    type: object
                                    nullable: true
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                        example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                                      name:
                                        type: string
                                        example: Default
                                      url:
                                        type: string
                                        example: >-
                                          https://cdn.tryhamsa.com/audio-assets/default.mp3?Signature=...
                                        description: Signed playable URL for the track.
                                      duration:
                                        type: number
                                        example: 32.5
                                        nullable: true
                                        description: Track duration in seconds.
                                    description: >-
                                      The selected ambient sound track with a
                                      signed playable URL, falling back to the
                                      system "Default" track when nothing is
                                      selected. Only populated on the get-by-id
                                      endpoints.
                              tools:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    persistentId:
                                      type: string
                                      example: payment-api
                                    toolId:
                                      type: string
                                      format: uuid
                                      example: uuid-123
                                    version:
                                      type: number
                                      example: 2
                                    toolType:
                                      type: string
                                      example: FUNCTION
                                    nodeId:
                                      type: string
                                      example: node-payment
                                    testResult:
                                      type: object
                                      additionalProperties: true
                                    overrides:
                                      type: object
                                    selectedFunctions:
                                      type: array
                                      items:
                                        type: string
                                      description: >-
                                        MCP tools only: function names exposed
                                        to the model. Absent on a global
                                        reference = all enabled, [] = none; a
                                        node reference uses the first entry.
                                      example:
                                        - create_ticket
                                        - get_ticket
                              knowledgeBaseItemsIds:
                                type: array
                                items:
                                  type: string
                                  format: uuid
                                example:
                                  - 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e
                              voiceDictionaryIds:
                                type: array
                                items:
                                  type: string
                                  format: uuid
                                  example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                              phoneNumber:
                                type: object
                                nullable: true
                                properties:
                                  type:
                                    type: string
                                    example: TWILIO
                                  id:
                                    type: string
                                    format: uuid
                                    example: phone-123
                              webhookUrl:
                                type: string
                                example: https://example.com/webhook
                                nullable: true
                              webhookAuth:
                                type: object
                                nullable: true
                                properties:
                                  authKey:
                                    type: string
                                    example: bearer
                                  authSecret:
                                    type: string
                                    example: secret
                              workflow:
                                type: object
                                nullable: true
                                additionalProperties: true
                              resolvedWebTools:
                                type: array
                                items:
                                  type: object
                                  additionalProperties: true
                              outcomeResponseShape:
                                type: object
                                nullable: true
                                description: >-
                                  outcomeResponseShape following the OpenAPI
                                  JSON format standards!
                              alwaysOnExtractVariables:
                                type: object
                                nullable: true
                                description: >-
                                  Variables extracted at every node of the flow,
                                  configured once on the agent instead of per
                                  node. Absent, or an empty variables list,
                                  means always-on extraction is off.
                                properties:
                                  variables:
                                    type: array
                                    items:
                                      type: object
                              account:
                                type: object
                                properties:
                                  plan:
                                    type: string
                                    example: Enterprise
                              createdAt:
                                type: string
                                format: date-time
                                example: '2024-11-18T20:54:00.054Z'
                              updatedAt:
                                type: string
                                format: date-time
                                example: '2024-11-18T00:00:00.000Z'
                              draft:
                                type: object
                                description: The revision you asked for.
                                properties:
                                  revision:
                                    type: string
                                    format: uuid
                                    example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
                                  savedBy:
                                    $ref: '#/components/schemas/AgentVersionActor'
                                  updatedAt:
                                    type: string
                                    format: date-time
                                    example: '2026-10-28T09:15:00.000Z'
                              policyIds:
                                type: array
                                items:
                                  type: string
                                  format: uuid
                                example:
                                  - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
                                description: >-
                                  IDs of the policies the agent uses, in the
                                  order they were added. The same shape as
                                  `policyIds` in the create and update body.
                              policyStates:
                                type: object
                                additionalProperties:
                                  type: boolean
                                example:
                                  5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
                                description: >-
                                  Whether each of those policies is on (`true`)
                                  or off (`false`), by ID.
                              guardrailIds:
                                type: array
                                items:
                                  type: string
                                  format: uuid
                                example:
                                  - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
                                description: >-
                                  IDs of the guardrails the agent uses, in the
                                  order they were added. The same shape as
                                  `guardrailIds` in the create and update body.
                              guardrailStates:
                                type: object
                                additionalProperties:
                                  type: boolean
                                example:
                                  5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
                                description: >-
                                  Whether each of those guardrails is on
                                  (`true`) or off (`false`), by ID.
                              functionMacroIds:
                                type: array
                                items:
                                  type: string
                                  format: uuid
                                example:
                                  - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
                                description: >-
                                  IDs of the functions and macros the agent
                                  uses, in the order they were added. The same
                                  shape as `functionMacroIds` in the create and
                                  update body.
                              functionMacroStates:
                                type: object
                                additionalProperties:
                                  type: boolean
                                example:
                                  5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
                                description: >-
                                  Whether each of those functions and macros is
                                  on (`true`) or off (`false`), by ID.
                          - type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
                              type:
                                type: string
                                enum:
                                  - Transcription Agent
                                example: Transcription Agent
                              name:
                                type: string
                                example: My Transcription Agent
                              isTranslationEnabled:
                                type: boolean
                                example: false
                                default: false
                                description: >-
                                  Only allowed when type is 'Transcription
                                  Agent'.
                              translationTargetLanguage:
                                type: string
                                enum:
                                  - en
                                  - ar
                                  - fr
                                  - es
                                  - pt
                                  - zh
                                  - ru
                                example: en
                                default: null
                                nullable: true
                                description: >-
                                  Only allowed when type is 'Transcription
                                  Agent'.
                              llm:
                                type: object
                                properties:
                                  provider:
                                    type: string
                                    example: Gemini
                                  model:
                                    type: string
                                    example: gemini-3.5-flash-lite
                                  temperature:
                                    type: number
                                    example: 0.2
                                  baseUrl:
                                    type: string
                                    nullable: true
                                    example: null
                                  apiKey:
                                    type: string
                                    example: '{{secrets.OPENAI_KEY}}'
                                    description: >-
                                      Only when the stored key is exactly one
                                      `{{secrets.NAME}}` reference. Left out
                                      when a raw key is stored: a raw key is
                                      never returned.
                                  reasoningEffort:
                                    type: string
                                    example: null
                                    nullable: true
                                    maxLength: 50
                                    description: >-
                                      Custom provider only (ignored for others).
                                      Free text, trimmed; blank or null clears
                                      it.
                                  hasApiKey:
                                    type: boolean
                                    example: true
                                    description: >-
                                      Whether a key or secret reference is
                                      stored.
                                  apiKeyLast4:
                                    type: string
                                    nullable: true
                                    example: '7890'
                                    description: >-
                                      The last four characters of a stored raw
                                      key of 16 characters or more that holds no
                                      `{{`; `null` otherwise, including for a
                                      secret reference.
                              callSettings:
                                type: object
                                properties:
                                  speakerIdentification:
                                    type: boolean
                                    example: false
                                  genderDetection:
                                    type: boolean
                                    example: false
                                  vadActivationThreshold:
                                    type: number
                                    example: 0.5
                                    minimum: 0.2
                                    maximum: 0.9
                                  userInactivityTimeout:
                                    type: number
                                    minimum: 5
                                    maximum: 60
                                    example: 15
                                  maxCallDuration:
                                    type: number
                                    minimum: 30
                                    maximum: 3600
                                    example: 300
                                  timezone:
                                    type: string
                                    example: Asia/Amman
                                    nullable: true
                                  maxCallDurationBehavior:
                                    type: object
                                    nullable: true
                                    description: >-
                                      What happens when the call reaches
                                      maxCallDuration. Null or absent = end the
                                      call (default). With 'transfer_call',
                                      `transfer` is required and has the same
                                      shape as a flow Transfer call step.
                                    properties:
                                      action:
                                        type: string
                                        enum:
                                          - end_call
                                          - transfer_call
                                        example: transfer_call
                                      message:
                                        type: string
                                        maxLength: 2000
                                        nullable: true
                                        example: >-
                                          We have reached the time limit, let me
                                          transfer you to {{agent_name}}.
                                        description: >-
                                          What the agent says before ending or
                                          transferring, or with `messageType`
                                          `prompt`, the instruction it follows.
                                          May contain {{variables}}.
                                      messageType:
                                        type: string
                                        enum:
                                          - static
                                          - prompt
                                        default: static
                                        description: >-
                                          `static` says `message` as written.
                                          `prompt` gives it to the agent as an
                                          instruction, and it writes what to say;
                                          allowed only with `transfer_call`.
                                          Ending the call is always `static`.
                                      transfer:
                                        type: object
                                        nullable: true
                                        description: >-
                                          Required when action is 'transfer_call';
                                          ignored otherwise.
                                        properties:
                                          phoneNumberType:
                                            type: string
                                            enum:
                                              - e164
                                              - variable
                                            example: e164
                                          phoneNumber:
                                            type: string
                                            example: '+962790000000'
                                            description: >-
                                              E.164 number when phoneNumberType is
                                              e164, a {{variable}} reference when
                                              variable.
                                          transferType:
                                            type: string
                                            enum:
                                              - cold
                                            default: cold
                                          sipHeaders:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                id:
                                                  type: string
                                                name:
                                                  type: string
                                                value:
                                                  type: string
                                  contextManager:
                                    type: object
                                    nullable: true
                                    description: >-
                                      Smart context manager switch. Null or
                                      absent = the runtime default.
                                    properties:
                                      mode:
                                        type: string
                                        enum:
                                          - active
                                          - 'off'
                                        example: active
                              phoneNumber:
                                type: object
                                nullable: true
                                properties:
                                  type:
                                    type: string
                                    example: TWILIO
                                  id:
                                    type: string
                                    format: uuid
                                    example: phone-123
                              webhookUrl:
                                type: string
                                example: https://example.com/webhook
                                nullable: true
                              webhookAuth:
                                type: object
                                nullable: true
                                properties:
                                  authKey:
                                    type: string
                                    example: bearer
                                  authSecret:
                                    type: string
                                    example: secret
                              outcomeResponseShape:
                                type: object
                                nullable: true
                                description: >-
                                  outcomeResponseShape following the OpenAPI
                                  JSON format standards!
                              alwaysOnExtractVariables:
                                type: object
                                nullable: true
                                description: >-
                                  Variables extracted at every node of the flow,
                                  configured once on the agent instead of per
                                  node. Absent, or an empty variables list,
                                  means always-on extraction is off.
                                properties:
                                  variables:
                                    type: array
                                    items:
                                      type: object
                              account:
                                type: object
                                properties:
                                  plan:
                                    type: string
                                    example: Enterprise
                              createdAt:
                                type: string
                                format: date-time
                                example: '2024-11-18T20:54:00.054Z'
                              updatedAt:
                                type: string
                                format: date-time
                                example: '2024-11-18T00:00:00.000Z'
                              draft:
                                type: object
                                description: The revision you asked for.
                                properties:
                                  revision:
                                    type: string
                                    format: uuid
                                    example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
                                  savedBy:
                                    $ref: '#/components/schemas/AgentVersionActor'
                                  updatedAt:
                                    type: string
                                    format: date-time
                                    example: '2026-10-28T09:15:00.000Z'
                        description: 'With `revision`: the agent config at that revision.'
                        properties:
                          id:
                            type: string
                            format: uuid
                            example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                          type:
                            type: string
                            example: Single Prompt
                            nullable: true
                          name:
                            type: string
                            example: Customer Support Agent
                          conversation:
                            type: object
                            properties:
                              greetingMessage:
                                type: string
                                example: Hello, how can I help you today?
                              greetingMessageType:
                                type: string
                                nullable: true
                                example: null
                              preamble:
                                type: string
                                example: You are a helpful assistant.
                              pokeMessages:
                                type: array
                                items:
                                  type: string
                                example:
                                  - Are you still there?
                                  - Take your time, I'm here when you're ready.
                              params:
                                type: object
                                additionalProperties:
                                  type: string
                                example:
                                  customer_name: Sara
                                  order_number: '48213'
                              alignment:
                                type: object
                                properties:
                                  greetingMessage:
                                    type: string
                                    example: ltr
                                  preamble:
                                    type: string
                                    example: ltr
                          voice:
                            type: object
                            properties:
                              voiceId:
                                type: string
                                nullable: true
                                example: en-US-Neural2-A
                              voiceRecordId:
                                type: string
                                nullable: true
                                example: null
                              voiceRecord:
                                type: object
                                nullable: true
                                description: TTS voice details
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  name:
                                    type: string
                                  provider:
                                    type: string
                                  language:
                                    type: string
                                  image:
                                    type: string
                                    nullable: true
                                  languageCode:
                                    type: string
                                    nullable: true
                                  voiceRecord:
                                    type: object
                                    nullable: true
                              lang:
                                type: string
                                nullable: true
                                example: en
                              ttsParams:
                                type: object
                                nullable: true
                                additionalProperties:
                                  type: string
                          llm:
                            type: object
                            properties:
                              provider:
                                type: string
                                example: openai
                              model:
                                type: string
                                example: gpt-4
                              temperature:
                                type: number
                                example: 0.2
                              baseUrl:
                                type: string
                                nullable: true
                                example: null
                              apiKey:
                                type: string
                                example: '{{secrets.OPENAI_KEY}}'
                                description: >-
                                  Only when the stored key is exactly one
                                  `{{secrets.NAME}}` reference. Left out when a
                                  raw key is stored: a raw key is never
                                  returned.
                              hasApiKey:
                                type: boolean
                                example: true
                                description: Whether a key or secret reference is stored.
                              apiKeyLast4:
                                type: string
                                nullable: true
                                example: '7890'
                                description: >-
                                  The last four characters of a stored raw key
                                  of 16 characters or more that holds no `{{`;
                                  `null` otherwise, including for a secret
                                  reference.
                          callSettings:
                            type: object
                            properties:
                              noiseCancellation:
                                type: string
                                example: TELEPHONY_OPTIMIZED
                              cancelNoisePer:
                                type: string
                                nullable: true
                                example: conversation
                              interrupt:
                                type: boolean
                                example: true
                              responseDelay:
                                type: number
                                example: 400
                              userInactivityTimeout:
                                type: number
                                example: 15
                              maxCallDuration:
                                type: number
                                example: 300
                              silenceThreshold:
                                type: number
                                example: 800
                              backgroundNoise:
                                type: boolean
                                example: false
                              thinkingVoice:
                                type: boolean
                                example: false
                              speakerIdentification:
                                type: boolean
                                example: false
                              agenticRag:
                                type: boolean
                                example: false
                              languageDialectSwitcher:
                                type: boolean
                                example: false
                              minInterruptionDuration:
                                type: number
                                example: 0.5
                              vadActivationThreshold:
                                type: number
                                example: 0.5
                              enableAutoGainControl:
                                type: boolean
                                example: false
                              sendDenoisedToStt:
                                type: boolean
                                example: false
                              genderDetection:
                                type: boolean
                                example: false
                              smartCallEnd:
                                type: boolean
                                example: false
                              waitForUserToSpeakFirst:
                                type: integer
                                enum:
                                  - 0
                                  - 1
                                  - 2
                                example: 0
                                description: >-
                                  Who speaks first. `0`: the agent greets first
                                  (never waits). `1`: the agent always waits for
                                  the caller to speak first. `2`: the agent
                                  waits only on outbound calls, and greets first
                                  on inbound and web calls.
                          tools:
                            type: array
                            nullable: true
                            description: Agent tools configuration
                            items:
                              type: object
                          knowledgeBaseItemsIds:
                            type: array
                            items:
                              type: string
                              format: uuid
                            example:
                              - 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e
                          voiceDictionaryIds:
                            type: array
                            items:
                              type: string
                              format: uuid
                            example:
                              - 4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a
                          phoneNumber:
                            type: object
                            nullable: true
                            properties:
                              type:
                                type: string
                                example: TWILIO
                              id:
                                type: string
                                format: uuid
                                example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                          webhookUrl:
                            type: string
                            nullable: true
                            example: null
                          webhookAuth:
                            type: object
                            nullable: true
                          workflow:
                            description: >-
                              Workflow graph for Flow Agents; `null` for other
                              agent types.
                            allOf:
                              - $ref: '#/components/schemas/Workflow'
                          outcomeResponseShape:
                            type: object
                            nullable: true
                            description: Expected outcome response structure
                          resolvedWebTools:
                            type: array
                            nullable: true
                            description: Resolved web tools with overrides applied
                            items:
                              type: object
                          createdAt:
                            type: string
                            format: date-time
                            example: '2024-01-15T10:30:00Z'
                          updatedAt:
                            type: string
                            format: date-time
                            example: '2024-01-15T10:30:00Z'
                          account:
                            type: object
                            description: User account plan information
                            properties:
                              plan:
                                type: string
                                nullable: true
                                example: pro
                          policyIds:
                            type: array
                            items:
                              type: string
                              format: uuid
                            example:
                              - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
                            description: >-
                              IDs of the policies the agent uses, in the order
                              they were added. The same shape as `policyIds` in
                              the create and update body.
                          policyStates:
                            type: object
                            additionalProperties:
                              type: boolean
                            example:
                              5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
                            description: >-
                              Whether each of those policies is on (`true`) or
                              off (`false`), by ID.
                          guardrailIds:
                            type: array
                            items:
                              type: string
                              format: uuid
                            example:
                              - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
                            description: >-
                              IDs of the guardrails the agent uses, in the order
                              they were added. The same shape as `guardrailIds`
                              in the create and update body.
                          guardrailStates:
                            type: object
                            additionalProperties:
                              type: boolean
                            example:
                              5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
                            description: >-
                              Whether each of those guardrails is on (`true`) or
                              off (`false`), by ID.
                          functionMacroIds:
                            type: array
                            items:
                              type: string
                              format: uuid
                            example:
                              - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
                            description: >-
                              IDs of the functions and macros the agent uses, in
                              the order they were added. The same shape as
                              `functionMacroIds` in the create and update body.
                          functionMacroStates:
                            type: object
                            additionalProperties:
                              type: boolean
                            example:
                              5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
                            description: >-
                              Whether each of those functions and macros is on
                              (`true`) or off (`false`), by ID.
                        type: object
                        title: A revision (revision=...)
        '400':
          description: Invalid request (for example a missing or invalid field).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '403':
          description: Your API key or role does not have the `agents:read` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '404':
          description: >-
            Voice agent not found, you have no draft (`MemberDraftNotFound`,
            reason `NO_DRAFT`), or the revision is unknown
            (`UnknownBaseRevision`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AgentDraft:
      type: object
      description: A member's draft with its full config and test values.
      properties:
        id:
          type: string
          format: uuid
          description: Draft ID.
          example: 9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47
        author:
          $ref: '#/components/schemas/AgentDraftAuthor'
        status:
          type: string
          enum:
            - open
            - proposed
            - published
            - discarded
            - expired
          description: >-
            `open`: being edited by its author. `proposed`: waiting for review.
            `published`: went into a version. `discarded`: thrown away.
            `expired`: left unsaved for 7 days.
          example: open
        baseVersionNumber:
          type: integer
          description: The version the draft started from.
          example: 4
        versionsBehind:
          type: integer
          description: >-
            How many versions the draft is behind the version new drafts start
            from. `0` when it is up to date; update it with `POST
            /draft/rebase`.
          example: 0
        changedPaths:
          type: array
          items:
            type: string
          description: >-
            The settings that differ from the base version, as paths in the
            agent body.
          example:
            - conversation.preamble
            - llm.temperature
        revision:
          type: string
          format: uuid
          description: >-
            The draft's current revision. Send it as `baseRevision` when you
            save, so you don't overwrite a newer save.
          example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
        proposedAt:
          type: string
          format: date-time
          description: When it was proposed.
          example: '2026-10-28T09:15:00.000Z'
        proposalNote:
          type: string
          description: The note sent with the proposal.
          example: New opening line for Saudi callers.
        lastSentBack:
          type: object
          description: The last time a reviewer sent it back.
          properties:
            by:
              $ref: '#/components/schemas/AgentDraftAuthor'
            note:
              type: string
              example: Please keep the greeting under 10 seconds.
            at:
              type: string
              format: date-time
              example: '2026-10-28T09:15:00.000Z'
        combinedFrom:
          type: array
          description: The proposals a reviewer combined into this draft.
          items:
            type: object
            properties:
              draftId:
                type: string
                format: uuid
                example: 9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47
              revision:
                type: string
                format: uuid
                example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
              author:
                $ref: '#/components/schemas/AgentDraftAuthor'
        expiresAt:
          type: string
          format: date-time
          description: >-
            An open draft expires 7 days after its last save. Not set while
            proposed.
          example: '2026-11-04T09:15:00.000Z'
        publishedAs:
          type: integer
          description: The version number it was published as (`published` only).
          example: 5
        closedBy:
          $ref: '#/components/schemas/AgentDraftAuthor'
          description: Who published or discarded it.
        closedAt:
          type: string
          format: date-time
          example: '2026-10-28T09:15:00.000Z'
        closedNote:
          type: string
          description: The note left when it was discarded.
          example: Covered by the new FAQ flow.
        lastVia:
          $ref: '#/components/schemas/AgentDraftVia'
          description: Where the last save came from.
        proposedVia:
          $ref: '#/components/schemas/AgentDraftVia'
          description: Where the proposal came from.
        updatedAt:
          type: string
          format: date-time
          description: When the author last saved.
          example: '2026-10-28T09:15:00.000Z'
        valueKeys:
          type: array
          items:
            type: string
          description: Names of the draft's test values, sorted. `[]` when none.
          example:
            - ORDER_ID
        agentId:
          type: string
          format: uuid
          example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
        config:
          $ref: '#/components/schemas/AgentDraftConfig'
        values:
          $ref: '#/components/schemas/AgentDraftTestValues'
        createdAt:
          type: string
          format: date-time
          example: '2026-10-28T09:15:00.000Z'
    AgentVersionActor:
      type: object
      description: A project member.
      properties:
        id:
          type: string
          format: uuid
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        name:
          type: string
          example: Sara Ahmad
    Workflow:
      type: object
      description: >-
        Flow Agent workflow graph. Stored on the agent and only meaningful when
        `type` is `"Flow Agent"`. Holds the graph `nodes`, the `edges`
        connecting them, and workflow-level `customVariables`. Agent-level
        configuration (voice, llm, call settings, tools, webhooks) lives in the
        top-level agent fields, **not** inside this object.
      required:
        - nodes
        - edges
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNode'
          description: The workflow nodes (the flow graph).
        edges:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEdge'
          description: Edges connecting nodes in the builder canvas.
        customVariables:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowVariable'
          default: []
          description: Workflow-level variables available across nodes.
      example:
        nodes:
          - id: 2ZHj3IUpJFc-83H2-f8d3
            type: start
            label: Start
            message: Hello, how can I help you today?
            messageType: prompt
            position:
              x: 0
              'y': 0
            metadata:
              version: 1
            transitions: []
        edges: []
        customVariables:
          - id: z5QsyxUbrKPjYMGaMj1e1
            name: customer_name
            dataType: string
            description: ''
            defaultValue: john
            extractionPrompt: ''
            enumValues: []
    AgentVersionError:
      type: object
      properties:
        code:
          type: integer
          description: Service error code (8400, 8403, 8404, 8409, ...).
          example: 8409
        message:
          type: string
          example: >-
            Your draft changed in another tab or through your API key. Reload it
            and try again.
        messageKey:
          type: string
          description: Stable error key.
          example: DraftStaleRevision
        params:
          type: object
          additionalProperties: true
          description: >-
            Details. `reason` names the case (for example `STALE_REVISION`,
            `NO_DRAFT`, `SESSION_ONLY`); `action` names a missing permission
            (for example `agents:deploy`).
          example:
            reason: STALE_REVISION
            revision: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
    AgentDraftAuthor:
      type: object
      description: A project member.
      properties:
        id:
          type: string
          format: uuid
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        name:
          type: string
          example: Sara Ahmad
        email:
          type: string
          nullable: true
          example: sara@example.com
    AgentDraftVia:
      type: object
      description: Where the change came from.
      properties:
        kind:
          type: string
          enum:
            - dashboard
            - api_key
          example: api_key
        keyRef:
          type: string
          description: The API key's reference (`api_key` only).
          example: sk_live_4f2a
        keyName:
          type: string
          description: The API key's name (`api_key` only).
          example: CRM sync
    AgentDraftConfig:
      oneOf:
        - type: object
          properties:
            id:
              type: string
              format: uuid
              example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
            type:
              type: string
              enum:
                - Single Prompt
                - Flow Agent
                - Transcription Agent
              example: Flow Agent
            name:
              type: string
              example: My Flow Agent
            conversation:
              type: object
              properties:
                greetingMessage:
                  type: string
                  example: Hello, how can I help you today?
                greetingMessageType:
                  type: string
                  example: STATIC
                  nullable: true
                  enum:
                    - STATIC
                    - PROMPT
                preamble:
                  type: string
                  example: >-
                    You are a helpful assistant that will answer users
                    questions.
                pokeMessages:
                  type: array
                  items:
                    type: string
                  example:
                    - Are you still there?
                    - Take your time, I'm here when you're ready.
                params:
                  type: object
                  additionalProperties:
                    type: string
                  example:
                    customer_name: Sara
                    order_number: '48213'
                alignment:
                  type: object
                  properties:
                    greetingMessage:
                      type: string
                      example: ltr
                    preamble:
                      type: string
                      example: ltr
            voice:
              type: object
              properties:
                voiceId:
                  type: string
                  example: voice-123
                  nullable: true
                voiceRecordId:
                  type: string
                  format: uuid
                  example: 2e77fa73-180e-4b96-80c6-e87363bed3e4
                  nullable: true
                voiceRecord:
                  type: object
                  nullable: true
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: voice-record-123
                    name:
                      type: string
                      example: English Voice
                    provider:
                      type: string
                      example: elevenlabs
                    ttsParams:
                      type: object
                      properties:
                        voiceId:
                          type: string
                          example: voice-123
                        dialect:
                          type: string
                          example: PLS
                        language:
                          type: string
                          example: ar
                    language:
                      type: string
                      example: en
                lang:
                  type: string
                  enum:
                    - ar
                    - en
                  example: en
                config:
                  type: object
                  properties:
                    expressiveness:
                      type: number
                      minimum: 0
                      maximum: 2
                      example: 1
                      default: 1
                      deprecated: true
                      description: >-
                        No longer changes how calls sound: see `casualMode` and
                        `autoEmotion`.
                    preferredSttModel:
                      type: string
                      enum:
                        - Hamsa-STT-S4
                        - Hamsa-STT-S3
                        - Hamsa-STT-English
                      example: Hamsa-STT-S4
                      default: Hamsa-STT-S4
                    casualMode:
                      type: boolean
                      example: false
                      description: Casual mode. `false` for an agent that never set it.
                    autoEmotion:
                      type: boolean
                      example: true
                      description: Auto Emotion. `false` for an agent that never set it.
                    useReferenceAudio:
                      type: boolean
                      example: true
                      description: >-
                        Use reference audio. `true` for an agent that never set
                        it.
            llm:
              type: object
              properties:
                provider:
                  type: string
                  example: Gemini
                model:
                  type: string
                  example: gemini-3.5-flash-lite
                temperature:
                  type: number
                  example: 0.2
                baseUrl:
                  type: string
                  nullable: true
                  example: null
                apiKey:
                  type: string
                  example: '{{secrets.OPENAI_KEY}}'
                  description: >-
                    Only when the stored key is exactly one `{{secrets.NAME}}`
                    reference. Left out when a raw key is stored: a raw key is
                    never returned.
                reasoningEffort:
                  type: string
                  example: null
                  nullable: true
                  maxLength: 50
                  description: >-
                    Custom provider only (ignored for others). Free text,
                    trimmed; blank or null clears it.
                hasApiKey:
                  type: boolean
                  example: true
                  description: Whether a key or secret reference is stored.
                apiKeyLast4:
                  type: string
                  nullable: true
                  example: '7890'
                  description: >-
                    The last four characters of a stored raw key of 16
                    characters or more that holds no `{{`; `null` otherwise,
                    including for a secret reference.
            callSettings:
              type: object
              properties:
                noiseCancellation:
                  type: string
                  example: disabled
                cancelNoisePer:
                  type: string
                  nullable: true
                  example: conversation
                interrupt:
                  type: boolean
                  example: true
                responseDelay:
                  type: number
                  example: 400
                userInactivityTimeout:
                  type: number
                  example: 15
                maxCallDuration:
                  type: number
                  example: 300
                silenceThreshold:
                  type: number
                  example: 800
                backgroundNoise:
                  type: boolean
                  example: false
                thinkingVoice:
                  type: boolean
                  example: false
                speakerIdentification:
                  type: boolean
                  example: false
                agenticRag:
                  type: boolean
                  example: false
                genderDetection:
                  type: boolean
                  example: false
                smartCallEnd:
                  type: boolean
                  example: false
                languageDialectSwitcher:
                  type: boolean
                  example: false
                waitForUserToSpeakFirst:
                  type: integer
                  enum:
                    - 0
                    - 1
                    - 2
                  default: 0
                  example: 0
                minInterruptionDuration:
                  type: number
                  example: 0.5
                  minimum: 0
                  maximum: 1.5
                vadActivationThreshold:
                  type: number
                  example: 0.5
                  minimum: 0.2
                  maximum: 0.9
                enableAutoGainControl:
                  type: boolean
                  example: false
                sendDenoisedToStt:
                  type: boolean
                  example: false
                promptEnhancer:
                  type: string
                  enum:
                    - disabled
                    - basic
                    - advanced
                  example: basic
                  default: basic
                enableEnhancedTurnTaking:
                  type: boolean
                  example: false
                  default: false
                smartCallEndPrompt:
                  type: string
                  example: >-
                    Terminate the call when: (1) all customer inquiries have
                    been resolved, (2) the conversation has reached a natural
                    conclusion, (3) the customer's goal has been achieved, or
                    (4) further conversation would be unproductive. Use this
                    tool only when you've achieved the primary objective of the
                    call.
                  nullable: true
                timezone:
                  type: string
                  example: Asia/Amman
                  nullable: true
                  description: >-
                    IANA time zone name the agent uses to resolve local
                    date/time during conversations.
                maxCallDurationBehavior:
                  type: object
                  nullable: true
                  description: >-
                    What happens when the call reaches maxCallDuration. Null or
                    absent = end the call (default). With 'transfer_call',
                    `transfer` is required and has the same shape as a flow
                    Transfer call step.
                  properties:
                    action:
                      type: string
                      enum:
                        - end_call
                        - transfer_call
                      example: transfer_call
                    message:
                      type: string
                      maxLength: 2000
                      nullable: true
                      example: >-
                        We have reached the time limit, let me transfer you to
                        {{agent_name}}.
                      description: >-
                        What the agent says before ending or transferring, or
                        with `messageType` `prompt`, the instruction it follows.
                        May contain {{variables}}.
                    messageType:
                      type: string
                      enum:
                        - static
                        - prompt
                      default: static
                      description: >-
                        `static` says `message` as written. `prompt` gives it to
                        the agent as an instruction, and it writes what to say;
                        allowed only with `transfer_call`. Ending the call is
                        always `static`.
                    transfer:
                      type: object
                      nullable: true
                      description: >-
                        Required when action is 'transfer_call'; ignored
                        otherwise.
                      properties:
                        phoneNumberType:
                          type: string
                          enum:
                            - e164
                            - variable
                          example: e164
                        phoneNumber:
                          type: string
                          example: '+962790000000'
                          description: >-
                            E.164 number when phoneNumberType is e164, a
                            {{variable}} reference when variable.
                        transferType:
                          type: string
                          enum:
                            - cold
                          default: cold
                        sipHeaders:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              value:
                                type: string
                contextManager:
                  type: object
                  nullable: true
                  description: >-
                    Smart context manager switch. Null or absent = the runtime
                    default.
                  properties:
                    mode:
                      type: string
                      enum:
                        - active
                        - 'off'
                      example: active
                onHoldMusicId:
                  type: string
                  format: uuid
                  example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                  nullable: true
                  description: >-
                    ID of the on-hold music track (system or project-owned)
                    played while the caller waits on hold.
                ambientSoundId:
                  type: string
                  format: uuid
                  example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                  nullable: true
                  description: >-
                    ID of the ambient sound track (system or project-owned)
                    played in the background during the call.
                onHoldMusic:
                  type: object
                  nullable: true
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                    name:
                      type: string
                      example: Default
                    url:
                      type: string
                      example: >-
                        https://cdn.tryhamsa.com/audio-assets/default.mp3?Signature=...
                      description: Signed playable URL for the track.
                    duration:
                      type: number
                      example: 32.5
                      nullable: true
                      description: Track duration in seconds.
                  description: >-
                    The selected on-hold music track with a signed playable URL,
                    falling back to the system "Default" track when nothing is
                    selected. Only populated on the get-by-id endpoints.
                ambientSound:
                  type: object
                  nullable: true
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                    name:
                      type: string
                      example: Default
                    url:
                      type: string
                      example: >-
                        https://cdn.tryhamsa.com/audio-assets/default.mp3?Signature=...
                      description: Signed playable URL for the track.
                    duration:
                      type: number
                      example: 32.5
                      nullable: true
                      description: Track duration in seconds.
                  description: >-
                    The selected ambient sound track with a signed playable URL,
                    falling back to the system "Default" track when nothing is
                    selected. Only populated on the get-by-id endpoints.
            tools:
              type: array
              items:
                type: object
                properties:
                  persistentId:
                    type: string
                    example: payment-api
                  toolId:
                    type: string
                    format: uuid
                    example: uuid-123
                  version:
                    type: number
                    example: 2
                  toolType:
                    type: string
                    example: FUNCTION
                  nodeId:
                    type: string
                    example: node-payment
                  testResult:
                    type: object
                    additionalProperties: true
                  overrides:
                    type: object
                  selectedFunctions:
                    type: array
                    items:
                      type: string
                    description: >-
                      MCP tools only: function names exposed to the model.
                      Absent on a global reference = all enabled, [] = none; a
                      node reference uses the first entry.
                    example:
                      - create_ticket
                      - get_ticket
            knowledgeBaseItemsIds:
              type: array
              items:
                type: string
                format: uuid
              example:
                - 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e
            voiceDictionaryIds:
              type: array
              items:
                type: string
                format: uuid
                example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
            phoneNumber:
              type: object
              nullable: true
              properties:
                type:
                  type: string
                  example: TWILIO
                id:
                  type: string
                  format: uuid
                  example: phone-123
            webhookUrl:
              type: string
              example: https://example.com/webhook
              nullable: true
            webhookAuth:
              type: object
              nullable: true
              properties:
                authKey:
                  type: string
                  example: bearer
                authSecret:
                  type: string
                  example: secret
            workflow:
              type: object
              nullable: true
              additionalProperties: true
            resolvedWebTools:
              type: array
              items:
                type: object
                additionalProperties: true
            outcomeResponseShape:
              type: object
              nullable: true
              description: >-
                outcomeResponseShape following the OpenAPI JSON format
                standards!
            alwaysOnExtractVariables:
              type: object
              nullable: true
              description: >-
                Variables extracted at every node of the flow, configured once
                on the agent instead of per node. Absent, or an empty variables
                list, means always-on extraction is off.
              properties:
                variables:
                  type: array
                  items:
                    type: object
            account:
              type: object
              properties:
                plan:
                  type: string
                  example: Enterprise
            createdAt:
              type: string
              format: date-time
              example: '2024-11-18T20:54:00.054Z'
            updatedAt:
              type: string
              format: date-time
              example: '2024-11-18T00:00:00.000Z'
            policyIds:
              type: array
              items:
                type: string
                format: uuid
              example:
                - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
              description: >-
                IDs of the policies the agent uses, in the order they were
                added. The same shape as `policyIds` in the create and update
                body.
            policyStates:
              type: object
              additionalProperties:
                type: boolean
              example:
                5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
              description: >-
                Whether each of those policies is on (`true`) or off (`false`),
                by ID.
            guardrailIds:
              type: array
              items:
                type: string
                format: uuid
              example:
                - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
              description: >-
                IDs of the guardrails the agent uses, in the order they were
                added. The same shape as `guardrailIds` in the create and update
                body.
            guardrailStates:
              type: object
              additionalProperties:
                type: boolean
              example:
                5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
              description: >-
                Whether each of those guardrails is on (`true`) or off
                (`false`), by ID.
            functionMacroIds:
              type: array
              items:
                type: string
                format: uuid
              example:
                - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
              description: >-
                IDs of the functions and macros the agent uses, in the order
                they were added. The same shape as `functionMacroIds` in the
                create and update body.
            functionMacroStates:
              type: object
              additionalProperties:
                type: boolean
              example:
                5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
              description: >-
                Whether each of those functions and macros is on (`true`) or off
                (`false`), by ID.
        - type: object
          properties:
            id:
              type: string
              format: uuid
              example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
            type:
              type: string
              enum:
                - Transcription Agent
              example: Transcription Agent
            name:
              type: string
              example: My Transcription Agent
            isTranslationEnabled:
              type: boolean
              example: false
              default: false
              description: Only allowed when type is 'Transcription Agent'.
            translationTargetLanguage:
              type: string
              enum:
                - en
                - ar
                - fr
                - es
                - pt
                - zh
                - ru
              example: en
              default: null
              nullable: true
              description: Only allowed when type is 'Transcription Agent'.
            llm:
              type: object
              properties:
                provider:
                  type: string
                  example: Gemini
                model:
                  type: string
                  example: gemini-3.5-flash-lite
                temperature:
                  type: number
                  example: 0.2
                baseUrl:
                  type: string
                  nullable: true
                  example: null
                apiKey:
                  type: string
                  example: '{{secrets.OPENAI_KEY}}'
                  description: >-
                    Only when the stored key is exactly one `{{secrets.NAME}}`
                    reference. Left out when a raw key is stored: a raw key is
                    never returned.
                reasoningEffort:
                  type: string
                  example: null
                  nullable: true
                  maxLength: 50
                  description: >-
                    Custom provider only (ignored for others). Free text,
                    trimmed; blank or null clears it.
                hasApiKey:
                  type: boolean
                  example: true
                  description: Whether a key or secret reference is stored.
                apiKeyLast4:
                  type: string
                  nullable: true
                  example: '7890'
                  description: >-
                    The last four characters of a stored raw key of 16
                    characters or more that holds no `{{`; `null` otherwise,
                    including for a secret reference.
            callSettings:
              type: object
              properties:
                speakerIdentification:
                  type: boolean
                  example: false
                genderDetection:
                  type: boolean
                  example: false
                vadActivationThreshold:
                  type: number
                  example: 0.5
                  minimum: 0.2
                  maximum: 0.9
                userInactivityTimeout:
                  type: number
                  minimum: 5
                  maximum: 60
                  example: 15
                maxCallDuration:
                  type: number
                  minimum: 30
                  maximum: 3600
                  example: 300
                timezone:
                  type: string
                  example: Asia/Amman
                  nullable: true
                maxCallDurationBehavior:
                  type: object
                  nullable: true
                  description: >-
                    What happens when the call reaches maxCallDuration. Null or
                    absent = end the call (default). With 'transfer_call',
                    `transfer` is required and has the same shape as a flow
                    Transfer call step.
                  properties:
                    action:
                      type: string
                      enum:
                        - end_call
                        - transfer_call
                      example: transfer_call
                    message:
                      type: string
                      maxLength: 2000
                      nullable: true
                      example: >-
                        We have reached the time limit, let me transfer you to
                        {{agent_name}}.
                      description: >-
                        What the agent says before ending or transferring, or
                        with `messageType` `prompt`, the instruction it follows.
                        May contain {{variables}}.
                    messageType:
                      type: string
                      enum:
                        - static
                        - prompt
                      default: static
                      description: >-
                        `static` says `message` as written. `prompt` gives it to
                        the agent as an instruction, and it writes what to say;
                        allowed only with `transfer_call`. Ending the call is
                        always `static`.
                    transfer:
                      type: object
                      nullable: true
                      description: >-
                        Required when action is 'transfer_call'; ignored
                        otherwise.
                      properties:
                        phoneNumberType:
                          type: string
                          enum:
                            - e164
                            - variable
                          example: e164
                        phoneNumber:
                          type: string
                          example: '+962790000000'
                          description: >-
                            E.164 number when phoneNumberType is e164, a
                            {{variable}} reference when variable.
                        transferType:
                          type: string
                          enum:
                            - cold
                          default: cold
                        sipHeaders:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              value:
                                type: string
                contextManager:
                  type: object
                  nullable: true
                  description: >-
                    Smart context manager switch. Null or absent = the runtime
                    default.
                  properties:
                    mode:
                      type: string
                      enum:
                        - active
                        - 'off'
                      example: active
            phoneNumber:
              type: object
              nullable: true
              properties:
                type:
                  type: string
                  example: TWILIO
                id:
                  type: string
                  format: uuid
                  example: phone-123
            webhookUrl:
              type: string
              example: https://example.com/webhook
              nullable: true
            webhookAuth:
              type: object
              nullable: true
              properties:
                authKey:
                  type: string
                  example: bearer
                authSecret:
                  type: string
                  example: secret
            outcomeResponseShape:
              type: object
              nullable: true
              description: >-
                outcomeResponseShape following the OpenAPI JSON format
                standards!
            alwaysOnExtractVariables:
              type: object
              nullable: true
              description: >-
                Variables extracted at every node of the flow, configured once
                on the agent instead of per node. Absent, or an empty variables
                list, means always-on extraction is off.
              properties:
                variables:
                  type: array
                  items:
                    type: object
            account:
              type: object
              properties:
                plan:
                  type: string
                  example: Enterprise
            createdAt:
              type: string
              format: date-time
              example: '2024-11-18T20:54:00.054Z'
            updatedAt:
              type: string
              format: date-time
              example: '2024-11-18T00:00:00.000Z'
      description: >-
        The agent's config, in the same shape as `data` in Get Voice Agent (`GET
        /v2/voice-agents/{voiceAgentId}`).
      properties:
        id:
          type: string
          format: uuid
          example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
        type:
          type: string
          example: Single Prompt
          nullable: true
        name:
          type: string
          example: Customer Support Agent
        conversation:
          type: object
          properties:
            greetingMessage:
              type: string
              example: Hello, how can I help you today?
            greetingMessageType:
              type: string
              nullable: true
              example: null
            preamble:
              type: string
              example: You are a helpful assistant.
            pokeMessages:
              type: array
              items:
                type: string
              example:
                - Are you still there?
                - Take your time, I'm here when you're ready.
            params:
              type: object
              additionalProperties:
                type: string
              example:
                customer_name: Sara
                order_number: '48213'
            alignment:
              type: object
              properties:
                greetingMessage:
                  type: string
                  example: ltr
                preamble:
                  type: string
                  example: ltr
        voice:
          type: object
          properties:
            voiceId:
              type: string
              nullable: true
              example: en-US-Neural2-A
            voiceRecordId:
              type: string
              nullable: true
              example: null
            voiceRecord:
              type: object
              nullable: true
              description: TTS voice details
              properties:
                id:
                  type: string
                  format: uuid
                name:
                  type: string
                provider:
                  type: string
                language:
                  type: string
                image:
                  type: string
                  nullable: true
                languageCode:
                  type: string
                  nullable: true
                voiceRecord:
                  type: object
                  nullable: true
            lang:
              type: string
              nullable: true
              example: en
            ttsParams:
              type: object
              nullable: true
              additionalProperties:
                type: string
        llm:
          type: object
          properties:
            provider:
              type: string
              example: openai
            model:
              type: string
              example: gpt-4
            temperature:
              type: number
              example: 0.2
            baseUrl:
              type: string
              nullable: true
              example: null
            apiKey:
              type: string
              example: '{{secrets.OPENAI_KEY}}'
              description: >-
                Only when the stored key is exactly one `{{secrets.NAME}}`
                reference. Left out when a raw key is stored: a raw key is never
                returned.
            hasApiKey:
              type: boolean
              example: true
              description: Whether a key or secret reference is stored.
            apiKeyLast4:
              type: string
              nullable: true
              example: '7890'
              description: >-
                The last four characters of a stored raw key of 16 characters or
                more that holds no `{{`; `null` otherwise, including for a
                secret reference.
        callSettings:
          type: object
          properties:
            noiseCancellation:
              type: string
              example: TELEPHONY_OPTIMIZED
            cancelNoisePer:
              type: string
              nullable: true
              example: conversation
            interrupt:
              type: boolean
              example: true
            responseDelay:
              type: number
              example: 400
            userInactivityTimeout:
              type: number
              example: 15
            maxCallDuration:
              type: number
              example: 300
            silenceThreshold:
              type: number
              example: 800
            backgroundNoise:
              type: boolean
              example: false
            thinkingVoice:
              type: boolean
              example: false
            speakerIdentification:
              type: boolean
              example: false
            agenticRag:
              type: boolean
              example: false
            languageDialectSwitcher:
              type: boolean
              example: false
            minInterruptionDuration:
              type: number
              example: 0.5
            vadActivationThreshold:
              type: number
              example: 0.5
            enableAutoGainControl:
              type: boolean
              example: false
            sendDenoisedToStt:
              type: boolean
              example: false
            genderDetection:
              type: boolean
              example: false
            smartCallEnd:
              type: boolean
              example: false
            waitForUserToSpeakFirst:
              type: integer
              enum:
                - 0
                - 1
                - 2
              example: 0
              description: >-
                Who speaks first. `0`: the agent greets first (never waits).
                `1`: the agent always waits for the caller to speak first. `2`:
                the agent waits only on outbound calls, and greets first on
                inbound and web calls.
        tools:
          type: array
          nullable: true
          description: Agent tools configuration
          items:
            type: object
        knowledgeBaseItemsIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e
        voiceDictionaryIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a
        phoneNumber:
          type: object
          nullable: true
          properties:
            type:
              type: string
              example: TWILIO
            id:
              type: string
              format: uuid
              example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
        webhookUrl:
          type: string
          nullable: true
          example: null
        webhookAuth:
          type: object
          nullable: true
        workflow:
          description: Workflow graph for Flow Agents; `null` for other agent types.
          allOf:
            - $ref: '#/components/schemas/Workflow'
        outcomeResponseShape:
          type: object
          nullable: true
          description: Expected outcome response structure
        resolvedWebTools:
          type: array
          nullable: true
          description: Resolved web tools with overrides applied
          items:
            type: object
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        account:
          type: object
          description: User account plan information
          properties:
            plan:
              type: string
              nullable: true
              example: pro
        policyIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
          description: >-
            IDs of the policies the agent uses, in the order they were added.
            The same shape as `policyIds` in the create and update body.
        policyStates:
          type: object
          additionalProperties:
            type: boolean
          example:
            5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
          description: >-
            Whether each of those policies is on (`true`) or off (`false`), by
            ID.
        guardrailIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
          description: >-
            IDs of the guardrails the agent uses, in the order they were added.
            The same shape as `guardrailIds` in the create and update body.
        guardrailStates:
          type: object
          additionalProperties:
            type: boolean
          example:
            5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
          description: >-
            Whether each of those guardrails is on (`true`) or off (`false`), by
            ID.
        functionMacroIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
          description: >-
            IDs of the functions and macros the agent uses, in the order they
            were added. The same shape as `functionMacroIds` in the create and
            update body.
        functionMacroStates:
          type: object
          additionalProperties:
            type: boolean
          example:
            5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60: true
          description: >-
            Whether each of those functions and macros is on (`true`) or off
            (`false`), by ID.
      type: object
    AgentDraftTestValues:
      type: object
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 4000
      description: >-
        Test values: `NAME: value` pairs used only when you test this draft
        (they fill `{{NAME}}` variables). Names: capital letters, digits and
        `_`, starting with a letter, up to 64 characters; values 1-4,000
        characters; at most 50. A name can't be one the system fills in (such as
        `CURRENT_TIME`) or one of the agent's own variables.
      example:
        ORDER_ID: A-10293
    WorkflowNode:
      description: A workflow node. The concrete shape depends on the `type` discriminator.
      oneOf:
        - $ref: '#/components/schemas/WorkflowConversationNode'
        - $ref: '#/components/schemas/WorkflowStartNode'
        - $ref: '#/components/schemas/WorkflowToolNode'
        - $ref: '#/components/schemas/WorkflowWebToolNode'
        - $ref: '#/components/schemas/WorkflowTransferCallNode'
        - $ref: '#/components/schemas/WorkflowEndCallNode'
        - $ref: '#/components/schemas/WorkflowTransferAgentNode'
        - $ref: '#/components/schemas/WorkflowRouterNode'
        - $ref: '#/components/schemas/WorkflowSetLocalVariablesNode'
        - $ref: '#/components/schemas/WorkflowChangeAgentSettingsNode'
      discriminator:
        propertyName: type
        mapping:
          conversation: '#/components/schemas/WorkflowConversationNode'
          start: '#/components/schemas/WorkflowStartNode'
          tool: '#/components/schemas/WorkflowToolNode'
          web_tool: '#/components/schemas/WorkflowWebToolNode'
          transfer_call: '#/components/schemas/WorkflowTransferCallNode'
          end_call: '#/components/schemas/WorkflowEndCallNode'
          transfer_agent: '#/components/schemas/WorkflowTransferAgentNode'
          router: '#/components/schemas/WorkflowRouterNode'
          set_local_variables: '#/components/schemas/WorkflowSetLocalVariablesNode'
          change_agent_settings: '#/components/schemas/WorkflowChangeAgentSettingsNode'
    WorkflowEdge:
      type: object
      additionalProperties: false
      description: An edge between two nodes (ReactFlow canvas).
      required:
        - id
        - source
        - target
      properties:
        id:
          type: string
          description: Edge id (nanoid or UUID).
        source:
          type: string
          description: Source node id.
        target:
          type: string
          description: Target node id.
        sourceHandle:
          type: string
        targetHandle:
          type: string
        type:
          type: string
          default: default
          description: >-
            Edge render type (custom ReactFlow types like `deletable` are
            allowed).
        selected:
          type: boolean
          description: Canvas selection state.
        animated:
          type: boolean
          default: false
        hidden:
          type: boolean
          default: false
        metadata:
          type: object
          properties:
            transitionId:
              type: string
            label:
              type: string
            style:
              type: object
              additionalProperties: true
    WorkflowVariable:
      type: object
      additionalProperties: false
      description: A workflow variable (also used for extracted and nested variables).
      required:
        - id
        - name
        - dataType
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: Variable id — nanoid or author slug (e.g. `out_var_flights`).
        name:
          type: string
          maxLength: 50
          pattern: ^[a-z][a-z0-9_]*$
          description: Variable name (snake_case).
        description:
          type: string
          maxLength: 500
        dataType:
          type: string
          enum:
            - string
            - number
            - boolean
            - integer
            - array
            - object
        enumValues:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEnumValue'
          default: []
        isEnumEnabled:
          type: boolean
          default: false
        isRequired:
          type: boolean
          default: false
        defaultValue:
          nullable: true
          description: Default value (string, number, boolean, or null).
        extractionPrompt:
          type: string
        sourceNodeId:
          type: string
        sourceNodeType:
          type: string
        properties:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowVariable'
          description: Child variables (for `object` types).
        item:
          $ref: '#/components/schemas/WorkflowVariable'
          description: Element schema (for `array` types).
    WorkflowConversationNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - conversation
            messageType:
              type: string
              enum:
                - static
                - prompt
              default: prompt
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
            message:
              type: string
              description: >-
                Node message. May be empty. Supports `{{variable}}`
                interpolation.
            interruptMode:
              type: string
              enum:
                - inherit
                - enable
                - disable
              default: inherit
            extractVariables:
              $ref: '#/components/schemas/WorkflowExtractVariablesConfig'
            dtmfInputCapture:
              description: DTMF capture config, or null.
              nullable: true
              allOf:
                - $ref: '#/components/schemas/WorkflowDtmfInputCapture'
      description: Conversation node — the agent speaks/listens.
    WorkflowStartNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - start
            subType:
              type: string
              enum:
                - conversation
                - tool
              default: conversation
            messageType:
              type: string
              enum:
                - static
                - prompt
              default: prompt
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
            message:
              type: string
              description: >-
                Node message. May be empty. Supports `{{variable}}`
                interpolation.
            interrupt:
              type: boolean
              default: false
              description: Allow user to interrupt.
            extractVariables:
              $ref: '#/components/schemas/WorkflowExtractVariablesConfig'
            dtmfInputCapture:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/WorkflowDtmfInputCapture'
            timeout:
              type: integer
              minimum: 1
              default: 30000
              description: Timeout in milliseconds.
            overrideResponse:
              type: boolean
              default: false
              description: Override the default response with `customResponse`.
            customResponse:
              type: string
              description: >-
                Custom response shown instead of the default. Required when
                `overrideResponse` is true. Supports `{{variable}}`
                interpolation; may be empty.
            outputMapping:
              type: object
              additionalProperties:
                type: string
              default: {}
              description: Maps tool output fields to workflow variables.
            onErrorBehavior:
              type: string
              enum:
                - continue
                - retry
                - fail
              default: continue
            errorMessage:
              type: string
              description: >-
                Message spoken when the node errors. Supports `{{variable}}`
                interpolation; may be empty.
            processingMessage:
              type: string
              description: Message spoken while the node runs.
            processingMessageType:
              type: string
              enum:
                - static
                - prompt
              default: static
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
      description: Entry node of the workflow.
    WorkflowToolNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - tool
            parameters:
              type: array
              items:
                $ref: '#/components/schemas/WorkflowToolParameter'
              default: []
            timeout:
              type: integer
              minimum: 1
              default: 30000
              description: Timeout in milliseconds.
            extractVariables:
              $ref: '#/components/schemas/WorkflowExtractVariablesConfig'
            overrideResponse:
              type: boolean
              default: false
              description: Override the default response with `customResponse`.
            customResponse:
              type: string
              description: >-
                Custom response shown instead of the default. Required when
                `overrideResponse` is true. Supports `{{variable}}`
                interpolation; may be empty.
            outputMapping:
              type: object
              additionalProperties:
                type: string
              default: {}
              description: Maps tool output fields to workflow variables.
            onErrorBehavior:
              type: string
              enum:
                - continue
                - retry
                - fail
              default: continue
            errorMessage:
              type: string
              description: >-
                Message spoken when the node errors. Supports `{{variable}}`
                interpolation; may be empty.
            processingMessage:
              type: string
              description: Message spoken while the node runs.
            processingMessageType:
              type: string
              enum:
                - static
                - prompt
              default: static
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
      description: Function-tool execution node.
    WorkflowWebToolNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - web_tool
            processingMessage:
              type: string
              description: Message spoken while the web tool runs.
            processingMessageType:
              type: string
              enum:
                - static
                - prompt
              default: static
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
      description: Web-tool execution node.
    WorkflowTransferCallNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - transfer_call
            phoneNumber:
              type: string
              pattern: ^\+?[1-9]\d{1,14}$
              description: Destination phone number (E.164).
              example: '+14155552671'
            transferType:
              type: string
              enum:
                - warm
                - cold
              default: cold
            transferMessage:
              type: string
              description: >-
                Message spoken before transferring. Supports `{{variable}}`
                interpolation; may be empty.
            transferMessageType:
              type: string
              enum:
                - static
                - prompt
              default: prompt
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
            timeout:
              type: integer
              minimum: 1
              default: 30000
              description: Timeout in milliseconds.
            sipHeaders:
              type: array
              items:
                $ref: '#/components/schemas/WorkflowSipHeader'
              description: Custom SIP headers to attach to the transfer.
          required:
            - phoneNumber
      description: Transfer the call to a phone number.
    WorkflowEndCallNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - end_call
            finalMessage:
              type: string
              description: >-
                Final message before ending the call. Supports `{{variable}}`
                interpolation; may be empty.
            messageType:
              type: string
              enum:
                - static
                - prompt
              default: prompt
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
            reason:
              type: string
              enum:
                - completed
                - user_requested
                - error
                - timeout
              default: completed
      description: End the call.
    WorkflowTransferAgentNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - transfer_agent
            agentId:
              type: string
              minLength: 1
              description: Target voice agent id.
            timeout:
              type: integer
              minimum: 1
              default: 30000
              description: Timeout in milliseconds.
            transferMessage:
              type: string
              description: >-
                Message spoken before handing off. Supports `{{variable}}`
                interpolation; may be empty.
            transferMessageType:
              type: string
              enum:
                - static
                - prompt
              default: static
              description: >-
                Whether the message is a literal `static` string or a `prompt`
                for the LLM.
            handoffConversation:
              type: boolean
              default: false
              description: Pass the conversation transcript to the target agent.
            handoffVariables:
              type: boolean
              default: false
              description: Pass workflow variables to the target agent.
          required:
            - agentId
      description: Hand off to another voice agent.
    WorkflowRouterNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - router
      description: Routes to a branch based on its transitions.
    WorkflowSetLocalVariablesNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - set_local_variables
      description: Sets local/static variables (see base `staticVariables`).
    WorkflowChangeAgentSettingsNode:
      allOf:
        - $ref: '#/components/schemas/WorkflowNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - change_agent_settings
            settingsOverrides:
              type: object
              additionalProperties: true
              default: {}
              description: >-
                Agent-setting overrides applied at this node. Stored as-is and
                not field-validated (mirrors agent-level config).
      description: Overrides agent settings mid-flow.
    WorkflowEnumValue:
      type: object
      additionalProperties: false
      required:
        - value
      properties:
        value:
          type: string
          maxLength: 100
        label:
          type: string
          maxLength: 100
    WorkflowNodeBase:
      type: object
      description: >-
        Fields shared by every workflow node. Node objects are passthrough —
        extra builder-authored fields not listed here are preserved as-is.
      additionalProperties: true
      required:
        - id
        - type
        - position
        - metadata
      properties:
        id:
          type: string
          description: Unique node id (nanoid or UUID).
          example: 2ZHj3IUpJFc-83H2-f8d3
        type:
          type: string
          enum:
            - conversation
            - start
            - tool
            - web_tool
            - transfer_call
            - end_call
            - transfer_agent
            - router
            - set_local_variables
            - change_agent_settings
          description: Node type discriminator.
        label:
          type: string
          maxLength: 100
          description: Display label.
        description:
          type: string
          maxLength: 500
          description: Optional node description.
        isGlobal:
          type: boolean
          default: false
          description: Whether this is a global node.
        globalCondition:
          type: string
          description: >-
            Condition that activates a global node. Supports `{{variable}}`
            interpolation; may be empty.
        globalConditionType:
          type: string
          enum:
            - prompt
            - dtmf
          default: prompt
        globalDtmfKey:
          type: string
          enum:
            - '0'
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
            - '#'
            - '*'
          description: >-
            DTMF key that triggers the global node when `globalConditionType` is
            `dtmf`.
        globalReturnToSource:
          type: boolean
          default: false
        requiresDoubleConfirm:
          type: boolean
          default: false
        skipResponse:
          type: boolean
          default: false
        staticVariables:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStaticVariable'
        metadata:
          $ref: '#/components/schemas/WorkflowNodeMetadata'
        transitions:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowTransition'
          default: []
          description: Outgoing transitions to other nodes.
        position:
          $ref: '#/components/schemas/WorkflowPosition'
    WorkflowExtractVariablesConfig:
      type: object
      additionalProperties: false
      description: Variable extraction config for a node.
      properties:
        enabled:
          type: boolean
          default: false
        variables:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowVariable'
          default: []
    WorkflowDtmfInputCapture:
      type: object
      additionalProperties: false
      description: Captures DTMF digits into a variable.
      properties:
        enabled:
          type: boolean
          default: false
        variableName:
          type: string
          default: ''
          description: Variable to store captured digits (required when `enabled`).
        digitLimit:
          type: integer
          minimum: 1
          maximum: 20
        terminationKey:
          type: string
          enum:
            - '0'
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
            - '#'
            - '*'
        timeoutMs:
          type: integer
          minimum: 1000
          maximum: 30000
    WorkflowToolParameter:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          minLength: 1
        value:
          type: string
          description: >-
            Parameter value. Supports `{{variable}}` interpolation; may be
            empty.
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - object
          default: string
        required:
          type: boolean
          default: true
    WorkflowSipHeader:
      type: object
      required:
        - id
        - name
        - value
      properties:
        id:
          type: string
        name:
          type: string
        value:
          type: string
    WorkflowStaticVariable:
      type: object
      additionalProperties: false
      description: A statically-set variable.
      required:
        - id
        - name
        - dataType
        - value
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
        name:
          type: string
          maxLength: 50
          pattern: ^[a-z][a-z0-9_]*$
        description:
          type: string
          maxLength: 500
        dataType:
          type: string
          enum:
            - string
            - number
            - boolean
            - integer
            - array
            - object
        value:
          description: The static value (string, number, boolean, array, object, or null).
    WorkflowNodeMetadata:
      type: object
      additionalProperties: false
      description: Node metadata.
      properties:
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        version:
          type: integer
          minimum: 1
          default: 1
    WorkflowTransition:
      type: object
      additionalProperties: false
      description: A transition from one node to another, gated by a condition.
      required:
        - id
        - condition
        - targetNodeId
      properties:
        id:
          type: string
          description: Transition id (nanoid or UUID).
        name:
          type: string
        condition:
          $ref: '#/components/schemas/WorkflowCondition'
        targetNodeId:
          type: string
          description: Target node id, or an empty string if unconnected.
        priority:
          type: integer
          minimum: 0
          default: 0
        isEnabled:
          type: boolean
          default: true
        metadata:
          type: object
          properties:
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    WorkflowPosition:
      type: object
      description: Canvas position of the node.
      required:
        - x
        - 'y'
      properties:
        x:
          type: number
        'y':
          type: number
    WorkflowCondition:
      description: Transition condition. Shape depends on the `type` discriminator.
      oneOf:
        - $ref: '#/components/schemas/WorkflowNaturalLanguageCondition'
        - $ref: '#/components/schemas/WorkflowStructuredEquationCondition'
        - $ref: '#/components/schemas/WorkflowDtmfCondition'
        - $ref: '#/components/schemas/WorkflowAlwaysCondition'
        - $ref: '#/components/schemas/WorkflowAutoCondition'
      discriminator:
        propertyName: type
        mapping:
          natural_language: '#/components/schemas/WorkflowNaturalLanguageCondition'
          structured_equation: '#/components/schemas/WorkflowStructuredEquationCondition'
          dtmf: '#/components/schemas/WorkflowDtmfCondition'
          always: '#/components/schemas/WorkflowAlwaysCondition'
          auto: '#/components/schemas/WorkflowAutoCondition'
    WorkflowNaturalLanguageCondition:
      type: object
      additionalProperties: false
      required:
        - type
        - prompt
      properties:
        type:
          type: string
          enum:
            - natural_language
        prompt:
          type: string
          minLength: 1
          description: Natural-language condition prompt.
        description:
          type: string
          maxLength: 500
    WorkflowStructuredEquationCondition:
      type: object
      additionalProperties: false
      required:
        - type
        - conditions
      properties:
        type:
          type: string
          enum:
            - structured_equation
        logic:
          type: string
          enum:
            - all
            - any
          default: all
        conditions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WorkflowEquationCondition'
        description:
          type: string
          maxLength: 500
    WorkflowDtmfCondition:
      type: object
      additionalProperties: false
      required:
        - type
        - key
      properties:
        type:
          type: string
          enum:
            - dtmf
        key:
          type: string
          enum:
            - '0'
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
            - '#'
            - '*'
        description:
          type: string
          maxLength: 500
    WorkflowAlwaysCondition:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - always
        description:
          type: string
          default: Default path
    WorkflowAutoCondition:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - auto
        description:
          type: string
          default: Auto-advance
    WorkflowEquationCondition:
      type: object
      additionalProperties: false
      description: A single equation condition within a structured_equation.
      required:
        - variable
        - operator
        - value
      properties:
        variable:
          type: string
          pattern: ^[a-z][a-z0-9_]*$
        operator:
          type: string
          enum:
            - equals
            - not_equals
            - greater_than
            - less_than
            - greater_than_or_equal
            - less_than_or_equal
            - contains
            - not_contains
            - exists
            - not_exists
            - regex
        value:
          description: Comparison value (string, number, or boolean).
        description:
          type: string
          maxLength: 500
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.