> ## 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.

# Rebase Agent Draft

> Moves your draft onto the newest version after someone published. You merge the two yourself and send the result as `config`, which is applied over version `onTopOf`. Works for open and proposed drafts.



## OpenAPI

````yaml /api-reference/openapi.json post /v2/voice-agents/{voiceAgentId}/draft/rebase
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/rebase:
    post:
      summary: Update your agent draft onto the newest version
      description: >-
        Moves your draft onto the newest version after someone published. You
        merge the two yourself and send the result as `config`, which is applied
        over version `onTopOf`. Works for open and proposed drafts.
      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: header
          name: Idempotency-Key
          required: false
          description: >-
            Optional, up to 255 characters. Retry with the same key after a
            network error and you get the first answer back instead of the
            change being made twice (kept 10 minutes). Same key with a different
            body: 422 `IdempotencyKeyReused`. While the first request still
            runs: 409 `IdempotencyKeyInProgress`.
          schema:
            type: string
            maxLength: 255
            example: 0b6f3c1e-retry-1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - onTopOf
                - config
                - baseRevision
              properties:
                onTopOf:
                  type: integer
                  minimum: 1
                  description: The newest version number, which you merged your draft onto.
                  example: 5
                config:
                  $ref: '#/components/schemas/UpdateVoiceAgentV2Request'
                baseRevision:
                  type: string
                  format: uuid
                  description: >-
                    Your draft's current `revision`, the one the merge started
                    from.
                  example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
            examples:
              rebase:
                summary: Rebase onto v5
                value:
                  onTopOf: 5
                  baseRevision: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
                  config:
                    conversation:
                      preamble: You are a friendly support agent for Hamsa Telecom.
      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:
                      revision:
                        type: string
                        format: uuid
                        example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
                      draft:
                        $ref: '#/components/schemas/AgentDraftSummary'
        '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:update` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '404':
          description: Voice agent not found, or you have no draft (`MemberDraftNotFound`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '409':
          description: >-
            `onTopOf` is not the newest version (`DraftStaleBase`,
            `params.newest`), or `baseRevision` is not your draft's current
            revision (`DraftStaleRevision`). Or: Another request with the same
            `Idempotency-Key` is still running (`IdempotencyKeyInProgress`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '422':
          description: >-
            The `Idempotency-Key` was already used with a different body
            (`IdempotencyKeyReused`).
          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:
    UpdateVoiceAgentV2Request:
      type: object
      description: >-
        All fields are optional for updates. Include only the fields you want to
        update.
      properties:
        name:
          type: string
          description: Name of the voice agent (max 150 characters).
          maxLength: 150
          example: Updated Customer Support Agent
        conversation:
          type: object
          description: Conversation settings (partial update supported).
          properties:
            greetingMessage:
              type: string
              example: Welcome! How may I assist you?
              maxLength: 191
              description: Initial greeting message (max 191 characters).
            greetingMessageType:
              type: string
              nullable: true
              example: STATIC
              enum:
                - STATIC
                - PROMPT
                - null
              description: >-
                How the greeting is produced. `STATIC` speaks `greetingMessage`
                as written; `PROMPT` lets the LLM generate the greeting from
                `greetingMessage` as an instruction. `null` keeps the default
                behaviour.
            preamble:
              type: string
              example: You are a customer support assistant.
              description: System instruction/prompt for the agent.
            pokeMessages:
              type: array
              items:
                type: string
                maxLength: 5000
              example:
                - Are you still there?
              description: >-
                Messages the agent says when the caller goes quiet: up to 20,
                each up to 5,000 characters.
              maxItems: 20
            params:
              type: object
              additionalProperties:
                type: string
              example:
                customer_name: Sara
                order_number: '48213'
              description: >-
                Default values for the agent's variables, as `{"name":
                "value"}`. Names are written as `{{name}}`, so each must be
                letters, digits and `_`, not starting with a digit, and not
                `true`, `false`, `none`, `and`, `or`, `not`, `in`, `is`, `if` or
                `else` (`true`, `false` and `none` in any case). Other names are
                refused with a `JinjaName…` error that suggests a spelling, for
                example `customer_name` for `customer name`.
            alignment:
              type: object
              properties:
                greetingMessage:
                  type: string
                  example: ltr
                  description: >-
                    Text direction of the greeting in the editor: `ltr` left to
                    right, `rtl` right to left, `auto` taken from the text.
                  enum:
                    - ltr
                    - rtl
                    - auto
                preamble:
                  type: string
                  example: ltr
                  description: >-
                    Text direction of the prompt in the editor: `ltr` left to
                    right, `rtl` right to left, `auto` taken from the text.
                  enum:
                    - ltr
                    - rtl
                    - auto
              description: Text alignment settings.
        voice:
          type: object
          description: Voice settings (partial update supported).
          properties:
            voiceId:
              type: string
              nullable: true
              example: en-US-Neural2-B
              maxLength: 200
              description: TTS voice ID (max 200 characters).
            lang:
              type: string
              example: en
              enum:
                - ar
                - en
              description: Agent language.
            config:
              type: object
              description: Voice and speech-recognition tuning.
              properties:
                expressiveness:
                  type: number
                  minimum: 0
                  maximum: 2
                  default: 1
                  example: 1
                  description: >-
                    No longer changes how calls sound: use `casualMode` and
                    `autoEmotion`. Still accepted (0 to 2) and returned.
                  deprecated: true
                preferredSttModel:
                  type: string
                  enum:
                    - Hamsa-STT-S4
                    - Hamsa-STT-S3
                    - Hamsa-STT-English
                  example: Hamsa-STT-S4
                  description: >-
                    Speech-to-text model used to understand the caller.
                    `Hamsa-STT-S4` is the default Arabic model, `Hamsa-STT-S3`
                    is the previous Arabic model, and `Hamsa-STT-English` is
                    tuned for English callers. Older names (`Hamsa-STT-S2`,
                    `Hamsa-STT-S2-deprecated`, `Hamsa-STT-S3-beta`) are rejected
                    with `PreferredSttModelMustBeValid`; agents saved with them
                    are returned as `Hamsa-STT-S4` (S3-beta as `Hamsa-STT-S3`).
                casualMode:
                  type: boolean
                  example: false
                  description: >-
                    Casual mode: a relaxed, conversational delivery with natural
                    pauses. `true` turns it on, `false` turns it off. Leave it
                    out to keep the current value.
                autoEmotion:
                  type: boolean
                  example: true
                  description: >-
                    Auto Emotion: the voice adds emotion that fits what it says.
                    `true` turns it on, `false` turns it off. Leave it out to
                    keep the current value.
                useReferenceAudio:
                  type: boolean
                  example: true
                  description: >-
                    Use reference audio: the voice follows its reference
                    recording. `true` turns it on, `false` turns it off. Leave
                    it out to keep the current value.
        llm:
          type: object
          description: LLM configuration (partial update supported).
          properties:
            provider:
              type: string
              description: LLM provider. Values are case-sensitive.
              enum:
                - OpenAI
                - Gemini
                - Groq
                - Custom
              default: Gemini
              example: OpenAI
            model:
              type: string
              description: >-
                Model name. Valid values depend on `provider`: OpenAI (GPT-5,
                GPT-5-Mini, GPT-5-Nano, GPT-5.4-mini, gpt-6-luna, GPT-4.1,
                GPT-4.1-Mini, GPT-4.1-Nano, GPT-4o, GPT-4o-mini); Gemini (Gemini
                2.5-Pro, Gemini 2.5-Flash, gemini-3.1-flash-lite,
                gemini-3.5-flash-lite); Groq (openai/gpt-oss-120b,
                openai/gpt-oss-20b); Custom accepts any model name served by
                your endpoint. If you send a provider without a model, the
                provider's default is used (OpenAI: GPT-4.1-Mini, Gemini:
                gemini-3.5-flash-lite, Groq: openai/gpt-oss-20b). GPT-5,
                GPT-4.1, GPT-4o and Gemini 2.5-Pro need your own `apiKey` from 1
                December 2026 (see `apiKey`).
              default: gemini-3.5-flash-lite
              example: GPT-4.1
            temperature:
              type: number
              minimum: 0
              maximum: 1
              example: 0.8
              description: Temperature setting (0-1).
            baseUrl:
              type: string
              description: Custom base URL (required for custom provider).
              example: https://api.example.com
            apiKey:
              type: string
              example: sk-...
              description: >-
                Your own provider API key. Required for the `Custom` provider.
                Some flagship models also need your own key once their date
                passes: today GPT-5, GPT-4.1 and GPT-4o (OpenAI) and Gemini
                2.5-Pro (Gemini), from 1 December 2026. Until then they work
                without a key; after it, creating the agent, saving with
                `apiKey: null`, publishing or test-calling the draft, or
                starting a call on one of them without a key fails with `400
                LLMApiKeyRequiredForExpensiveModel`. The list and dates are
                managed by Hamsa and can change: `GET
                /v1/voice-agents/llm-catalog` returns the current `ownKey`,
                `status` and `enforceFrom` of every model. Send `null` to remove
                the stored key. Leave it out to keep the stored key; changing
                `provider` without sending a key removes it. An empty string is
                refused. Reads never return a raw key (see `hasApiKey`). On a
                call, if the provider refuses the key, or a `{{secrets.NAME}}`
                reference in it doesn't resolve, the call ends with status
                `FAILED` before the agent speaks.
              nullable: true
            reasoningEffort:
              type: string
              nullable: true
              maxLength: 50
              example: medium
              description: >-
                Reasoning effort passed as-is to a `Custom` endpoint. Ignored
                (stored as null) for other providers. Send an empty string or
                null to clear it.
        callSettings:
          type: object
          description: Call settings (partial update supported).
          properties:
            noiseCancellation:
              type: string
              description: Noise cancellation mode. Values are case-sensitive.
              enum:
                - DISABLED
                - TELEPHONY_OPTIMIZED
                - GENERAL_USE_CASES
              default: TELEPHONY_OPTIMIZED
              example: TELEPHONY_OPTIMIZED
            cancelNoisePer:
              type: string
              description: >-
                Apply noise cancellation once for the whole conversation
                (`CONVERSATION`) or on every turn (`TURN`). Required when
                `noiseCancellation` is not `DISABLED`.
              enum:
                - CONVERSATION
                - TURN
              default: CONVERSATION
              example: CONVERSATION
            interrupt:
              type: boolean
              example: true
              description: Allow user interruptions.
            responseDelay:
              type: integer
              minimum: 100
              maximum: 1500
              example: 500
              description: Response delay in milliseconds (100-1500). Whole number.
            minInterruptionDuration:
              type: number
              minimum: 0.2
              maximum: 1.5
              example: 0.6
              description: Minimum interruption duration in seconds (0.2-1.5).
            vadActivationThreshold:
              type: number
              minimum: 0.2
              maximum: 0.9
              example: 0.6
              description: Voice activity detection threshold (0.2-0.9).
            userInactivityTimeout:
              type: integer
              minimum: 5
              maximum: 60
              example: 20
              description: User inactivity timeout in seconds (5-60). Whole number.
            maxCallDuration:
              type: integer
              minimum: 30
              maximum: 3600
              example: 400
              description: >-
                Maximum call duration in seconds (30-3600). See
                `maxCallDurationBehavior` for what happens when it is reached.
                Whole number.
            silenceThreshold:
              type: integer
              minimum: 100
              example: 1000
              description: >-
                Silence, in whole milliseconds (100-5000), that ends the
                caller's turn.
              maximum: 5000
            backgroundNoise:
              type: boolean
              example: true
              description: Enable background noise.
            enableAutoGainControl:
              type: boolean
              example: true
              description: Enable automatic gain control.
            sendDenoisedToStt:
              type: boolean
              example: true
              description: Send denoised audio to STT.
            waitForUserToSpeakFirst:
              type: integer
              example: 1
              enum:
                - 0
                - 1
                - 2
              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.
              minimum: 0
              maximum: 2
            thinkingVoice:
              type: boolean
              example: true
              description: Enable thinking voice feature.
            speakerIdentification:
              type: boolean
              example: true
              description: Enable speaker identification.
            agenticRag:
              type: boolean
              example: true
              description: Enable agentic RAG.
            languageDialectSwitcher:
              type: boolean
              example: true
              description: Enable language dialect switcher.
            genderDetection:
              type: boolean
              example: true
              description: Enable gender detection.
            smartCallEnd:
              type: boolean
              example: true
              description: Enable smart call end detection.
            promptEnhancer:
              type: string
              enum:
                - disabled
                - basic
                - advanced
              default: basic
              example: basic
              description: How much Hamsa enhances your system prompt before the call.
            enableEnhancedTurnTaking:
              type: boolean
              default: false
              example: false
              description: >-
                Use the enhanced turn-taking pipeline (better handling of
                numbers and long digit sequences, fewer unwanted interruptions).
            smartCallEndPrompt:
              type: string
              nullable: true
              description: >-
                Instructions that tell the agent when to end the call. Used when
                `smartCallEnd` is enabled.
              maxLength: 10000
            timezone:
              type: string
              nullable: true
              default: null
              example: Asia/Amman
              description: >-
                IANA time zone the agent uses for dates and times, for example
                `Asia/Riyadh`. Write it with IANA capitals (`Asia/Kolkata`, not
                `asia/kolkata`). `null` uses UTC.
            maxCallDurationBehavior:
              type: object
              nullable: true
              default: null
              description: >-
                What happens when the call reaches `maxCallDuration`. `null`
                ends the call.
              properties:
                action:
                  type: string
                  enum:
                    - end_call
                    - transfer_call
                  description: End the call or transfer it.
                message:
                  type: string
                  maxLength: 2000
                  description: >-
                    What the agent says before ending or transferring, or with
                    `messageType` `prompt`, the instruction it follows. May
                    contain {{variables}}. Each `{{ }}` must be closed, in
                    order, not nested and not empty.
                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
                  description: >-
                    Required when `action` is `transfer_call`. The transfer is
                    always cold.
                  properties:
                    phoneNumberType:
                      type: string
                      enum:
                        - e164
                        - variable
                      description: >-
                        `e164` for a literal number, `variable` for a
                        `{{variable}}` reference.
                    phoneNumber:
                      type: string
                      example: '+962790000000'
                      description: >-
                        E.164 number, or a `{{variable}}` reference when
                        `phoneNumberType` is `variable`.
                    transferType:
                      type: string
                      enum:
                        - cold
                      default: cold
                      description: >-
                        Only `cold`: the call is handed over without an
                        introduction.
                    sipHeaders:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: >-
                              Header name. Letters, digits and
                              ``!#$%&'*+.^_`|~-``: no spaces or colons.
                            maxLength: 100
                            pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$
                            example: X-Customer-Id
                          value:
                            type: string
                            description: >-
                              Header value. Variables like `{{customer_id}}` are
                              filled in. One line, up to 1,000 characters.
                            maxLength: 1000
                          id:
                            type: string
                            description: Your ID for the header entry (any unique string).
                        required:
                          - name
                          - value
                          - id
                      description: >-
                        SIP headers sent with the transfer (SIP numbers). Up to
                        20; header names are unique, ignoring case.
                      maxItems: 20
                  required:
                    - phoneNumberType
                    - phoneNumber
              required:
                - action
            contextManager:
              type: object
              nullable: true
              default: null
              description: 'Smart context manager switch. `null`: off.'
              properties:
                mode:
                  type: string
                  enum:
                    - active
                    - 'off'
                  description: >-
                    `active`: keep the model's context short on long calls.
                    `off`: send the whole conversation.
              required:
                - mode
            onHoldMusicId:
              type: string
              format: uuid
              nullable: true
              default: null
              description: >-
                ID of an on-hold music track (a system track or one of your
                audio assets) played while tools run.
            ambientSoundId:
              type: string
              format: uuid
              nullable: true
              default: null
              description: >-
                ID of an ambient sound track (a system track or one of your
                audio assets) played in the background of the call.
        tools:
          type: array
          description: Web tools (replaces existing tools).
          items:
            type: object
            properties:
              persistentId:
                type: string
                description: Persistent identifier for the tool.
                example: tool_123
              toolId:
                type: string
                format: uuid
                description: UUID of the web tool.
                example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
              version:
                type: integer
                description: Tool version number.
                minimum: 1
                example: 1
              toolType:
                type: string
                description: Type of tool.
                enum:
                  - FUNCTION
                  - MCP
                  - WEB_TOOL
                example: FUNCTION
              nodeId:
                type: string
                description: Node ID for flow agents.
                example: node_1
              testResult:
                type: object
                description: Test result data.
                additionalProperties: true
              overrides:
                type: object
                description: >-
                  Settings that replace the tool's own for this agent only.
                  Leave out what you don't change.
                additionalProperties: true
                properties:
                  id:
                    type: string
                    description: ID of the tool these overrides apply to.
                  name:
                    type: string
                    description: Tool name the LLM sees.
                  nodeId:
                    type: string
                    description: Flow step the overrides apply to (flow agents).
                  serverUrl:
                    type: string
                    format: uri
                    description: URL the request goes to (HTTPS).
                  methodType:
                    type: string
                    description: 'HTTP method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`.'
                  description:
                    type: string
                    description: What the tool does, as the LLM sees it.
                  async:
                    type: boolean
                    description: Send the request without waiting for the response.
                  timeOut:
                    type: number
                    minimum: 1
                    maximum: 300
                    description: Request timeout in seconds.
                  authToken:
                    type: string
                    description: >-
                      Token sent as the tool's authorization. Use
                      `{{secrets.NAME}}` to reference a project secret.
                  httpHeaders:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        value:
                          type: string
                        disabled:
                          type: boolean
                      required:
                        - value
                    description: >-
                      Headers, keyed by name: `{"Name": {"value": "...",
                      "disabled": false}}`. `disabled: true` keeps the entry but
                      leaves it out of the request.
                  params:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        value:
                          anyOf:
                            - type: string
                            - type: number
                            - type: boolean
                            - type: object
                              additionalProperties: {}
                            - type: array
                        disabled:
                          type: boolean
                      required:
                        - value
                    description: >-
                      Parameters, keyed by name: `{"Name": {"value": "...",
                      "disabled": false}}`. `disabled: true` keeps the entry but
                      leaves the parameter out of the call completely: the agent
                      isn't asked for it and it isn't sent.
                  customHeaders:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        value:
                          type: string
                        disabled:
                          type: boolean
                      required:
                        - value
                    description: >-
                      Custom headers, keyed by name: `{"Name": {"value": "...",
                      "disabled": false}}`. `disabled: true` keeps the entry but
                      leaves it out of the request.
                  customParams:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        value:
                          anyOf:
                            - type: string
                            - type: number
                            - type: boolean
                            - type: object
                              additionalProperties: {}
                            - type: array
                        disabled:
                          type: boolean
                      required:
                        - value
                    description: >-
                      Custom parameters, keyed by name: `{"Name": {"value":
                      "...", "disabled": false}}`. `disabled: true` keeps the
                      entry but leaves it out of the request.
                  arrayBody:
                    type: string
                    description: Name of the body field that is sent as an array.
                  arrayBodyValue:
                    type: array
                    description: The array sent in `arrayBody`.
                  onHoldMusic:
                    type: boolean
                    description: Play on-hold music while the request runs.
                  selectedFunctions:
                    type: array
                    items:
                      type: string
                    description: 'MCP tools: the server functions this agent may call.'
                  functionParams:
                    type: object
                    additionalProperties:
                      type: object
                      additionalProperties:
                        type: object
                        properties:
                          value:
                            anyOf:
                              - type: string
                              - type: number
                              - type: boolean
                              - type: object
                                additionalProperties: {}
                              - type: array
                          disabled:
                            type: boolean
                        required:
                          - value
                    description: >-
                      MCP tools: fixed values for function parameters, by
                      function name.
              selectedFunctions:
                type: array
                items:
                  type: string
                description: >-
                  MCP tools only. Function names (from the MCP server) exposed
                  to the model. Omit to enable all functions; `[]` enables none.
            required:
              - persistentId
              - toolId
              - version
              - toolType
        knowledgeBaseItemsIds:
          type: array
          description: Knowledge base item UUIDs (replaces existing).
          items:
            type: string
            format: uuid
          example:
            - 48f7656f-098b-4c43-b165-7cfd2cc8ac30
        voiceDictionaryIds:
          type: array
          description: Voice dictionary UUIDs (replaces existing).
          items:
            type: string
            format: uuid
          example:
            - 48f7656f-098b-4c43-b165-7cfd2cc8ac30
        webhookUrl:
          type: string
          format: uri
          example: https://example.com/webhook
          description: >-
            Webhook URL for external integrations. `null` clears it (send
            `webhookAuth: null` too to clear its auth). An empty string or a
            value that isn't a URL is refused.
          nullable: true
        webhookAuth:
          type: object
          additionalProperties: true
          properties:
            authKey:
              type: string
              example: bearer
              description: >-
                Auth type (`bearer`, `basic`, `api-key`, `authorization`) or a
                custom header name.
            authSecret:
              type: string
              description: The secret, without a `Bearer ` or `Basic ` prefix.
              example: your_webhook_secret
          required:
            - authKey
            - authSecret
          description: >-
            Authentication for `webhookUrl`. `authKey` is the auth type and
            `authSecret` the secret: `bearer` sends `Authorization: Bearer
            <authSecret>`, `basic` sends `Authorization: Basic <authSecret>`,
            `api-key` sends `X-API-Key: <authSecret>`, `authorization` sends the
            secret as the whole `Authorization` value, and any other value is
            used as the header name. `null` removes it. `null` clears it.
          nullable: true
        workflow:
          description: >-
            Workflow update for Flow Agents. `nodes`, `edges` and
            `customVariables` are each replaced wholesale when provided; omitted
            keys keep their stored value.
          allOf:
            - $ref: '#/components/schemas/Workflow'
        outcomeResponseShape:
          type: object
          additionalProperties: true
          description: >-
            Recursive OpenAPI-style shape with 'type', 'properties', 'required',
            'items', ...etc. Please refer to the `OpenAPI Outcome Response
            Instructions` above for more information.
        isTranslationEnabled:
          type: boolean
          default: false
          description: >-
            Transcription Agent only. Translate the transcription into
            `translationTargetLanguage`.
        translationTargetLanguage:
          type: string
          nullable: true
          default: null
          enum:
            - en
            - ar
            - fr
            - es
            - pt
            - zh
            - ru
            - null
          description: Transcription Agent only. Target language for translation.
        alwaysOnExtractVariables:
          type: object
          nullable: true
          description: >-
            Live variables: values the agent keeps up to date after every caller
            turn, in any step of the call (flow agents). `null` turns them off.
          properties:
            variables:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  id:
                    type: string
                    pattern: ^[A-Za-z0-9_-]+$
                    description: 'Your ID for the variable: letters, digits, `_` and `-`.'
                  name:
                    type: string
                    maxLength: 50
                    pattern: ^[a-z][a-z0-9_]*$
                    description: >-
                      Variable name used in prompts and tools: lowercase
                      letters, digits and `_`, starting with a letter (max 50).
                  description:
                    type: string
                    maxLength: 500
                    description: What the value is, for the extraction model (max 500).
                  dataType:
                    type: string
                    enum:
                      - string
                      - number
                      - boolean
                      - integer
                      - array
                      - object
                    description: Type of the value.
                  enumValues:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          type: string
                          maxLength: 100
                          description: The value saved (max 100).
                        label:
                          type: string
                          maxLength: 100
                          description: Display label (max 100).
                      required:
                        - value
                    default: []
                    description: Allowed values when `isEnumEnabled` is true.
                  isEnumEnabled:
                    type: boolean
                    default: false
                    description: Limit the value to `enumValues`.
                  isRequired:
                    type: boolean
                    default: false
                    description: The agent asks for the value until it has it.
                  defaultValue:
                    anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                      - enum:
                          - 'null'
                        nullable: true
                        type: string
                    description: >-
                      Value before the caller gives one (string, number, boolean
                      or null).
                  extractionPrompt:
                    type: string
                    description: Extra instructions for extracting this value.
                  sourceNodeId:
                    type: string
                    description: Set by the flow builder. Leave it out.
                  sourceNodeType:
                    type: string
                    description: Set by the flow builder. Leave it out.
                  properties:
                    type: array
                    items: {}
                    description: 'For `object`: the fields of the object.'
                  item:
                    description: 'For `array`: the type of each item.'
                  mayBeUndefined:
                    type: boolean
                    description: Set by the flow builder. Leave it out.
                required:
                  - id
                  - name
                  - dataType
              default: []
              description: The live variables.
            backgroundExtraction:
              type: boolean
              description: Extract in the background without delaying the agent's reply.
        policyIds:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            IDs of the project policies this agent uses. Replaces the list in
            your draft; ones already in it keep their on/off switch, new ones
            start on. Unknown IDs: 404 `DirectiveNotInProject`.
          example:
            - 5f0c9a52-7a3e-4d0e-9a1f-1c2b3d4e5f60
        guardrailIds:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            IDs of the project guardrails this agent uses. Replaces the list in
            your draft; ones already in it keep their on/off switch, new ones
            start on. Unknown IDs: 404 `DirectiveNotInProject`.
          example:
            - 8a1b2c3d-4e5f-4061-8a7b-9c0d1e2f3a4b
        functionMacroIds:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            IDs of the project functions and macros this agent uses. Replaces
            the list in your draft; ones already in it keep their on/off switch,
            new ones start on. Unknown IDs: 404 `DirectiveNotInProject`.
          example:
            - 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f
    AgentDraftSummary:
      type: object
      description: A member's draft of the agent.
      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
    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
    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: []
    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
    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.