> ## 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 by ID

> Returns a draft with its full config and the config of the version it started from, so you can compare them. You can see your own drafts, and with `agents:review_drafts` others' proposals.



## OpenAPI

````yaml /api-reference/openapi.json get /v2/voice-agents/{voiceAgentId}/drafts/{draftId}
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}/drafts/{draftId}:
    get:
      summary: Get an agent draft
      description: >-
        Returns a draft with its full config and the config of the version it
        started from, so you can compare them. You can see your own drafts, and
        with `agents:review_drafts` others' proposals.
      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: path
          name: draftId
          required: true
          description: ID of the draft.
          schema:
            type: string
            format: uuid
            example: 9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      draft:
                        allOf:
                          - $ref: '#/components/schemas/AgentDraft'
                          - type: object
                            properties:
                              reviewers:
                                type: array
                                description: >-
                                  Reviewers who have the proposal open right
                                  now. Left out when none.
                                items:
                                  type: object
                                  properties:
                                    by:
                                      $ref: '#/components/schemas/AgentDraftAuthor'
                                    since:
                                      type: string
                                      format: date-time
                                      example: '2026-10-28T09:15:00.000Z'
                      baseConfig:
                        $ref: '#/components/schemas/AgentDraftConfig'
        '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, or no draft you can see (`DraftNotFound`).
          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'
    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
    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
    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
    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
    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
    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: []
    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.