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

# Create agent

> Create a new voice agent.



## OpenAPI

````yaml /api-reference/agents/agents.oas.yaml post /v1/agents
openapi: 3.0.3
info:
  title: SLNG Voice Agents API
  version: 1.0.0
  description: >
    Public API for managing Voice Agents, dispatching outbound calls, and
    creating web (non-telephony) sessions.


    Base URL: `https://api.agents.slng.ai`
  contact:
    name: SLNG Support
    email: support@slng.ai
servers:
  - url: https://api.agents.slng.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Voice agent CRUD.
  - name: Versions
    description: Agent configuration version history and restore.
  - name: Calls
    description: Call dispatch and status.
  - name: Sessions
    description: Web (non-telephony) sessions.
paths:
  /v1/agents:
    post:
      tags:
        - Agents
      summary: Create agent
      description: Create a new voice agent.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceAgentCreate'
            examples:
              basic-shared-agent:
                summary: Agent without tools
                value:
                  schema_version: 2
                  tool_mode: shared
                  name: Appointment Reminder
                  system_prompt: >-
                    You are a friendly appointment reminder for {{clinic_name}}.
                    Confirm the patient's upcoming visit or help them
                    reschedule. Keep responses to one or two sentences.
                  greeting: >-
                    Hi {{patient_name}}, this is a reminder from {{clinic_name}}
                    about your upcoming appointment.
                  language: en
                  region: eu-central
                  models:
                    stt: slng/deepgram/nova:3-en
                    llm: groq/openai/gpt-oss-120b
                    tts: slng/deepgram/aura:2-en
                    tts_voice: aura-2-thalia-en
                  tool_refs: []
                  mcp_refs: []
                  template_defaults:
                    clinic_name: Downtown Health Clinic
                    patient_name: there
              scheduling-agent-with-shared-tool:
                summary: Agent with an automatic Current Date and Time tool
                value:
                  schema_version: 2
                  tool_mode: shared
                  name: Scheduling Assistant
                  system_prompt: >-
                    You help callers schedule appointments for
                    {{practice_name}}. Use the current date and time before
                    offering slots.
                  greeting: >-
                    Hi {{patient_name}}, this is Ava from {{practice_name}}. I'm
                    calling to help you find a convenient appointment time.
                  language: en
                  region: eu-central
                  models:
                    stt: slng/deepgram/nova:3-en
                    llm: groq/openai/gpt-oss-120b
                    tts: slng/deepgram/aura:2-en
                    tts_voice: aura-2-thalia-en
                  tool_refs:
                    - attachment_id: f0d84ac5-7988-460c-995d-2ad9621c09bb
                      tool_id: 6da4eb89-6449-46d6-8f8d-469b93e15c58
                      version: 1
                      invocation: system
                      system:
                        triggers:
                          - event: call_start
                        arguments: []
                      config_overrides:
                        type: current_datetime
                        timezone: Europe/Madrid
                  mcp_refs: []
                  template_defaults:
                    practice_name: Greenfield Family Medicine
                    patient_name: Maria
              support-agent-with-custom-code-and-mcp:
                summary: Agent with published Custom Code and MCP tools
                value:
                  schema_version: 2
                  tool_mode: shared
                  name: Support Router
                  system_prompt: >-
                    You help callers with order questions for {{brand_name}}.
                    Use the attached tools to look up order status and find
                    current support information.
                  greeting: >-
                    Hi, thanks for calling {{brand_name}} support. How can I
                    help you today?
                  language: en
                  region: eu-central
                  models:
                    stt: slng/deepgram/nova:3-en
                    llm: groq/openai/gpt-oss-120b
                    tts: slng/deepgram/aura:2-en
                    tts_voice: aura-2-thalia-en
                  tool_refs:
                    - attachment_id: 266f57b3-e9bd-4246-9d42-fd112922e09d
                      tool_id: 75580a0c-d972-4d4d-a7eb-88af21c42eed
                      version: 1
                      invocation: model
                      description: Normalize a customer timestamp and return UTC.
                  mcp_refs:
                    - attachment_id: 00b3ce6d-a6d2-43a6-8ef7-7c4fb5d3c141
                      server_id: 6090c15c-708e-46a7-9c18-6411c11940e3
                      tool_name: search_support_docs
                      observed_schema_hash: >-
                        0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
                  template_defaults:
                    brand_name: Northwind
      responses:
        '201':
          description: Agent created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceAgentOut'
        '202':
          description: >-
            A referenced tool or dependency is still being prepared. Retry the
            same request after the number of seconds in the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfigPreparationStatus'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                duplicate-tool-id:
                  summary: Tool IDs must be unique within an agent
                  value:
                    detail: Duplicate tool id detected
                invalid-template:
                  summary: Prompt template syntax is invalid
                  value:
                    detail: 'Invalid template: Unmatched handlebars braces in template'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user-not-found:
                  summary: Authenticated user could not be resolved
                  value:
                    detail: User not found
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                no-organisation-membership:
                  summary: Caller has no accessible organisation
                  value:
                    detail: User is not a member of any organisation
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                deployment-not-found:
                  summary: No runtime is configured for this region
                  value:
                    detail: No runtime is configured for region 'us-east'
        '409':
          description: Conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                duplicate-agent-name:
                  summary: Agent name already exists in the organisation
                  value:
                    detail: Agent with name 'Appointment Reminder' already exists
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing-human-transfer-trunk:
                  summary: Human transfer requires outbound telephony
                  value:
                    detail: >-
                      sip_outbound_trunk_id is required when human transfer
                      tools are configured
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal-error:
                  summary: Unexpected application error
                  value:
                    detail: >-
                      An unexpected internal error occurred while creating the
                      agent.
        '502':
          description: Bad gateway.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                inbound-dispatch-rule-failed:
                  summary: Inbound call routing setup failed
                  value:
                    detail: Failed to create inbound dispatch rule
components:
  schemas:
    VoiceAgentCreate:
      type: object
      additionalProperties: false
      required:
        - name
        - system_prompt
        - greeting
        - language
        - region
        - models
      properties:
        name:
          type: string
          maxLength: 255
        system_prompt:
          type: string
          description: System prompt (Handlebars template).
        greeting:
          type: string
          description: Default greeting.
        inbound_greeting:
          type: string
          nullable: true
          description: Optional greeting override for inbound calls.
        outbound_greeting:
          type: string
          nullable: true
          description: Optional greeting override for outbound calls.
        language:
          type: string
          maxLength: 10
        region:
          type: string
          enum:
            - us-east
            - eu-central
            - ap-south
          description: Region where the agent runs.
        models:
          $ref: '#/components/schemas/ModelsConfig'
        llm_router_enabled:
          type: boolean
          default: true
          description: >
            Routes the agent's LLM traffic through SLNG's managed LLM routing
            layer.

            Enabled by default.
        idle_nudges:
          $ref: '#/components/schemas/IdleNudgesConfig'
          nullable: true
        enable_interruptions:
          type: boolean
          default: true
        schema_version:
          type: integer
          enum:
            - 2
          nullable: true
          description: >-
            AgentConfig schema version. Set this to 2 for portable shared-agent
            configuration documents.
        tool_mode:
          type: string
          enum:
            - shared
          default: shared
          description: New agents use the shared organisation tool library.
        tool_refs:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/ToolAttachment'
          default: []
          description: Published organisation or curated tools attached to this agent.
        mcp_refs:
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/McpAttachment'
          default: []
          description: MCP server tools attached to this agent.
        template_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
          description: >-
            Optional SLNG agent template. It cannot be combined with explicit
            tool_refs.
        sip_inbound_trunk_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
        sip_outbound_trunk_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
        template_defaults:
          type: object
          additionalProperties:
            type: string
          default: {}
        template_variable_options:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TemplateVariableOption'
          default: {}
          description: >
            Per-variable options for the input variables used in the prompt and

            greetings, keyed by variable name. Use this to mark an input
            variable

            optional.
        runtime_variables:
          type: array
          items:
            $ref: '#/components/schemas/RuntimeVariableDefinition'
          default: []
    VoiceAgentOut:
      type: object
      required:
        - id
        - organisation_id
        - name
        - system_prompt
        - greeting
        - language
        - region
        - models
        - idle_nudges
        - enable_interruptions
        - tool_mode
        - tools
        - tool_refs
        - mcp_refs
        - livekit_deployment
        - template_variables
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        organisation_id:
          $ref: '#/components/schemas/UUID'
        name:
          type: string
        system_prompt:
          type: string
        greeting:
          type: string
        inbound_greeting:
          type: string
          nullable: true
        outbound_greeting:
          type: string
          nullable: true
        language:
          type: string
        region:
          type: string
        models:
          $ref: '#/components/schemas/ModelsConfig'
        models_validation_error:
          type: string
          nullable: true
          description: >
            Set when the stored models configuration no longer validates against
            the

            current rules. In that case `models` is returned as stored, without

            validation.
        llm_router_enabled:
          type: boolean
          description: >-
            Whether the agent's LLM traffic is routed through SLNG's managed LLM
            routing layer.
        idle_nudges:
          $ref: '#/components/schemas/IdleNudgesConfig'
        enable_interruptions:
          type: boolean
        tool_mode:
          type: string
          enum:
            - legacy
            - shared
          description: Tool system fixed when the agent was created. New agents use shared.
        tools:
          type: array
          readOnly: true
          deprecated: true
          items:
            type: object
            additionalProperties: true
          description: >-
            Legacy compatibility output. New shared agents return an empty
            array. Use tool_refs and mcp_refs for all new configuration.
        tool_refs:
          type: array
          items:
            $ref: '#/components/schemas/ToolAttachment'
        mcp_refs:
          type: array
          items:
            $ref: '#/components/schemas/McpAttachment'
        livekit_deployment:
          type: string
          description: Name of the runtime deployment serving this agent.
        sip_inbound_trunk_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
        sip_outbound_trunk_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
        template_variables:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TemplateVariableMeta'
        runtime_variables:
          type: array
          items:
            $ref: '#/components/schemas/RuntimeVariableDefinition'
        created_at:
          $ref: '#/components/schemas/DateTime'
        updated_at:
          $ref: '#/components/schemas/DateTime'
        deleted_at:
          $ref: '#/components/schemas/DateTime'
          nullable: true
    AgentConfigPreparationStatus:
      type: object
      required:
        - state
        - candidate_hash
        - resource_hash
        - config
      properties:
        state:
          type: string
          enum:
            - ready
            - preparing
            - failed
        candidate_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Content hash of the prepared config document.
        resource_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Hash of the organisation resources the config depends on.
        dependency_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
          nullable: true
        preparation_operation_id:
          type: string
          nullable: true
        retry_after_seconds:
          type: integer
          minimum: 1
          maximum: 60
          nullable: true
          description: >-
            Suggested delay in seconds before retrying (also sent as the
            `Retry-After` header).
        config:
          $ref: '#/components/schemas/AgentConfigDocument'
      description: >
        Status returned while a config document references organisation
        resources

        that require resolution before it can be activated.
    ErrorResponse:
      type: object
      additionalProperties: true
      description: >
        Error payloads can vary depending on where the error is raised (edge
        gateway vs backend).


        Common shapes include:

        - `{ "error": "message" }`

        - `{ "detail": "message" }`

        - `{ "detail": [ { "loc": [...], "msg": "...", "type": "..." } ] }`
        (validation)
      properties:
        error:
          type: string
        detail:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
    ModelsConfig:
      type: object
      additionalProperties: false
      description: Model configuration for the agent runtime (STT + LLM + TTS).
      required:
        - stt
        - llm
        - tts
        - tts_voice
      properties:
        stt:
          type: string
          description: STT model (provider/model:variant).
          example: slng/deepgram/nova:3-en
        llm:
          type: string
          description: |
            LLM model (provider/model). Must be one of the supported models.
          enum:
            - bedrock-mantle/nvidia.nemotron-super-3-120b
            - bedrock-mantle/nvidia.nemotron-nano-3-30b
            - groq/openai/gpt-oss-120b
          example: groq/openai/gpt-oss-120b
        tts:
          type: string
          description: TTS model (provider/model:variant).
          example: slng/deepgram/aura:2-en
        tts_voice:
          type: string
          description: Voice identifier for TTS.
          example: aura-2-thalia-en
        stt_kwargs:
          type: object
          additionalProperties: true
          default: {}
        llm_kwargs:
          type: object
          additionalProperties: true
          default: {}
        tts_kwargs:
          type: object
          additionalProperties: true
          default: {}
        fallbacks:
          $ref: '#/components/schemas/ModelsFallbacks'
        stt_final_timeout_s:
          type: number
          nullable: true
          minimum: 0
          description: >-
            Optional STT soft-fallback timeout in seconds, measured from
            end-of-turn.
        llm_first_token_timeout_s:
          type: number
          nullable: true
          minimum: 0
          description: >-
            Optional LLM soft-fallback timeout in seconds, measured to first
            token.
        tts_first_audio_timeout_s:
          type: number
          nullable: true
          minimum: 0
          description: >-
            Optional TTS soft-fallback timeout in seconds, measured to first
            audio frame.
        failure_audio_enabled:
          type: boolean
          default: true
          description: >-
            When true, play technical-difficulties audio before hangup on
            terminal failures.
    IdleNudgesConfig:
      type: object
      additionalProperties: false
      required:
        - first_nudge_text
        - second_nudge_text
        - final_hangup_text
      properties:
        enabled:
          type: boolean
          default: true
        first_nudge_delay_seconds:
          type: integer
          minimum: 1
          default: 15
        second_nudge_delay_seconds:
          type: integer
          minimum: 1
          default: 30
        hangup_delay_seconds:
          type: integer
          minimum: 1
          default: 15
        first_nudge_text:
          type: string
          minLength: 1
          maxLength: 500
        second_nudge_text:
          type: string
          minLength: 1
          maxLength: 500
        final_hangup_text:
          type: string
          minLength: 1
          maxLength: 500
      description: >-
        Optional silence recovery behavior. The runtime can send two follow-up
        nudges, then speak a final message and hang up.
    ToolAttachment:
      type: object
      additionalProperties: false
      required:
        - attachment_id
        - tool_id
        - version
      properties:
        attachment_id:
          $ref: '#/components/schemas/UUID'
          description: >-
            Client-generated ID that is unique across this agent's tool_refs and
            mcp_refs.
        tool_id:
          $ref: '#/components/schemas/UUID'
        version:
          type: integer
          minimum: 1
          description: Immutable published tool version.
        description:
          type: string
          maxLength: 2000
          nullable: true
          description: Per-agent description shown to the model.
        invocation:
          type: string
          enum:
            - model
            - system
          default: model
        system:
          allOf:
            - $ref: '#/components/schemas/SystemToolConfig'
          nullable: true
          description: >-
            Required when invocation is system and omitted when invocation is
            model.
        execution_policy:
          allOf:
            - $ref: '#/components/schemas/ToolExecutionPolicy'
          nullable: true
        argument_overrides:
          type: object
          default: {}
          additionalProperties:
            $ref: '#/components/schemas/ScalarValueExpression'
        config_overrides:
          allOf:
            - $ref: '#/components/schemas/ToolConfigOverrides'
          nullable: true
      description: A published organisation or curated tool attached to an agent.
    McpAttachment:
      type: object
      additionalProperties: false
      required:
        - attachment_id
        - server_id
        - tool_name
        - observed_schema_hash
      properties:
        attachment_id:
          $ref: '#/components/schemas/UUID'
          description: >-
            Client-generated ID that is unique across this agent's tool_refs and
            mcp_refs.
        server_id:
          $ref: '#/components/schemas/UUID'
        tool_name:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_-]+$
        description:
          type: string
          maxLength: 2000
          nullable: true
          description: Per-agent description shown to the model.
        invocation:
          type: string
          enum:
            - model
          default: model
        execution_policy:
          allOf:
            - $ref: '#/components/schemas/ToolExecutionPolicy'
          nullable: true
        argument_overrides:
          type: object
          default: {}
          additionalProperties:
            $ref: '#/components/schemas/ScalarValueExpression'
        observed_schema_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Hash of the MCP tool schema you reviewed when attaching it.
      description: >-
        One tool from an MCP server attached to an agent. MCP tools are
        model-invoked.
    UUID:
      type: string
      format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
    TemplateVariableOption:
      type: object
      additionalProperties: false
      properties:
        required:
          type: boolean
          default: true
      description: |
        Write-time options for a prompt/greeting input variable.
        Set `required: false` to mark the variable optional.
    RuntimeVariableDefinition:
      type: object
      additionalProperties: false
      required:
        - name
        - description
      properties:
        name:
          type: string
          maxLength: 64
          description: Runtime variable name available to the model during the call.
        description:
          type: string
          maxLength: 500
          description: LLM-visible description of what value should be stored.
    TemplateVariableMeta:
      type: object
      additionalProperties: true
      properties:
        required:
          type: boolean
        default:
          type: string
    DateTime:
      type: string
      format: date-time
      example: '2026-01-15T10:30:00Z'
    AgentConfigDocument:
      type: object
      additionalProperties: true
      description: >
        Canonical agent configuration document, exactly as produced by the agent

        config download endpoints. The document is a portable, secret-free

        representation of the agent's configuration; API Request authentication
        is

        carried as organisation Vault secret references. Treat it as an opaque
        file:

        download, store, and re-import it without modification.
    ModelsFallbacks:
      type: object
      additionalProperties: false
      properties:
        stt:
          type: array
          items:
            type: string
          default: []
        llm:
          type: array
          items:
            type: string
          default: []
        tts:
          type: array
          items:
            $ref: '#/components/schemas/TtsFallbackModel'
          default: []
    SystemToolConfig:
      type: object
      additionalProperties: false
      required:
        - triggers
      properties:
        triggers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/SystemTrigger'
        arguments:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/SystemArgument'
      description: >-
        Triggers and arguments for a tool that the runtime invokes
        automatically.
    ToolExecutionPolicy:
      type: object
      additionalProperties: false
      properties:
        pre_action_message:
          allOf:
            - $ref: '#/components/schemas/PreActionMessage'
          nullable: true
      description: Execution-time policy for an attached tool.
    ScalarValueExpression:
      description: >-
        A literal string, boolean, integer, or number, or one full-value
        reference such as {{input_name}}, {{$VAULT_VARIABLE}}, or {{@call_id}}.
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
    ToolConfigOverrides:
      oneOf:
        - $ref: '#/components/schemas/ApiRequestOverrides'
        - $ref: '#/components/schemas/EndCallOverrides'
        - $ref: '#/components/schemas/VoicemailDetectionOverrides'
        - $ref: '#/components/schemas/TransferCallOverrides'
        - $ref: '#/components/schemas/SendSmsOverrides'
        - $ref: '#/components/schemas/CurrentDatetimeOverrides'
        - $ref: '#/components/schemas/UserPhoneNumberOverrides'
      discriminator:
        propertyName: type
    TtsFallbackModel:
      type: object
      additionalProperties: false
      required:
        - model
        - voice
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 200
        voice:
          type: string
          minLength: 1
          maxLength: 200
    SystemTrigger:
      type: object
      additionalProperties: false
      required:
        - event
      properties:
        event:
          $ref: '#/components/schemas/SystemEvent'
        source_attachment_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
          description: >-
            Required for tool_succeeded and tool_failed. Omit it for other
            events.
      description: A call event that runs an attached tool automatically.
    SystemArgument:
      type: object
      additionalProperties: false
      required:
        - name
        - type
        - source
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        type:
          $ref: '#/components/schemas/SystemArgumentType'
        required:
          type: boolean
          default: false
        description:
          type: string
          maxLength: 2000
          nullable: true
        source:
          $ref: '#/components/schemas/SystemArgumentSource'
    PreActionMessage:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          default: false
        text:
          allOf:
            - $ref: '#/components/schemas/TemplateStringExpression'
          nullable: true
        wait:
          type: boolean
          default: false
      description: >-
        Optional message spoken before the tool runs. Text is required when
        enabled is true.
    ApiRequestOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - api_request
        url:
          type: string
          maxLength: 2000
          nullable: true
    EndCallOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - end_call
        goodbye_message:
          allOf:
            - $ref: '#/components/schemas/TemplateStringExpression'
          nullable: true
        wait_for_completion:
          type: boolean
          nullable: true
    VoicemailDetectionOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - voicemail_detection
        prompt:
          allOf:
            - $ref: '#/components/schemas/TemplateStringExpression'
          nullable: true
    TransferCallOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - transfer_call
        destination:
          allOf:
            - $ref: '#/components/schemas/ScalarValueExpression'
          nullable: true
    SendSmsOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - send_sms
        recipient:
          allOf:
            - $ref: '#/components/schemas/ScalarValueExpression'
          nullable: true
        body:
          allOf:
            - $ref: '#/components/schemas/TemplateStringExpression'
          nullable: true
        from_number:
          allOf:
            - $ref: '#/components/schemas/ScalarValueExpression'
          nullable: true
    CurrentDatetimeOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - current_datetime
        timezone:
          type: string
          nullable: true
          description: IANA timezone, such as Europe/Madrid.
        prompt:
          allOf:
            - $ref: '#/components/schemas/TemplateStringExpression'
          nullable: true
    UserPhoneNumberOverrides:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - user_phone_number
        prompt:
          allOf:
            - $ref: '#/components/schemas/TemplateStringExpression'
          nullable: true
    SystemEvent:
      type: string
      enum:
        - call_start
        - first_user_message
        - call_end
        - tool_succeeded
        - tool_failed
    SystemArgumentType:
      type: string
      enum:
        - string
        - integer
        - number
        - boolean
        - string[]
        - integer[]
        - number[]
        - boolean[]
        - transcript_messages
        - transcript_text
    SystemArgumentSource:
      oneOf:
        - $ref: '#/components/schemas/SystemArgumentSourceConstant'
        - $ref: '#/components/schemas/SystemArgumentSourceTemplate'
        - $ref: '#/components/schemas/SystemArgumentSourceTranscriptMessages'
        - $ref: '#/components/schemas/SystemArgumentSourceTranscriptText'
        - $ref: '#/components/schemas/SystemArgumentSourceContext'
      discriminator:
        propertyName: type
        mapping:
          constant:
            $ref: '#/components/schemas/SystemArgumentSourceConstant'
          template:
            $ref: '#/components/schemas/SystemArgumentSourceTemplate'
          transcript_messages:
            $ref: '#/components/schemas/SystemArgumentSourceTranscriptMessages'
          transcript_text:
            $ref: '#/components/schemas/SystemArgumentSourceTranscriptText'
          first_user_message:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          call_id:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          room_name:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          job_id:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          agent_id:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          agent_name:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          phone_number:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          trigger_event:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
          call_end_reason:
            $ref: '#/components/schemas/SystemArgumentSourceContext'
    TemplateStringExpression:
      type: object
      additionalProperties: false
      required:
        - segments
      properties:
        segments:
          type: array
          minItems: 1
          maxItems: 64
          items:
            oneOf:
              - $ref: '#/components/schemas/TemplateStringLiteralSegment'
              - $ref: '#/components/schemas/TemplateStringValueSegment'
            discriminator:
              propertyName: type
      description: Text built from literal and runtime expression segments.
    SystemArgumentSourceConstant:
      type: object
      additionalProperties: false
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - constant
        value:
          $ref: '#/components/schemas/JsonValue'
    SystemArgumentSourceTemplate:
      type: object
      additionalProperties: false
      required:
        - type
        - template
      properties:
        type:
          type: string
          enum:
            - template
        template:
          type: string
          minLength: 1
          maxLength: 2000
    SystemArgumentSourceTranscriptMessages:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - transcript_messages
        max_messages:
          type: integer
          minimum: 1
          default: 200
          nullable: true
    SystemArgumentSourceTranscriptText:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - transcript_text
        max_messages:
          type: integer
          minimum: 1
          default: 200
          nullable: true
    SystemArgumentSourceContext:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - first_user_message
            - call_id
            - room_name
            - job_id
            - agent_id
            - agent_name
            - phone_number
            - trigger_event
            - call_end_reason
    TemplateStringLiteralSegment:
      type: object
      additionalProperties: false
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - literal
        value:
          type: string
          maxLength: 2000
      description: Fixed text in a runtime template.
    TemplateStringValueSegment:
      type: object
      additionalProperties: false
      required:
        - type
        - expression
      properties:
        type:
          type: string
          enum:
            - expression
        expression:
          type: string
          description: >-
            A full-value reference such as {{input_name}}, {{$VAULT_VARIABLE}},
            or {{@call_id}}.
      description: A value resolved when the tool runs.
    JsonValue:
      description: Any finite JSON value.
      nullable: true
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
        - type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````