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

# Replace agent

> Replace a voice agent (full update).



## OpenAPI

````yaml /api-reference/agents/agents.oas.yaml put /v1/agents/{agent_id}
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: Calls
    description: Call dispatch and status.
  - name: Sessions
    description: Web (non-telephony) sessions.
paths:
  /v1/agents/{agent_id}:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    put:
      tags:
        - Agents
      summary: Replace agent
      description: Replace a voice agent (full update).
      operationId: replaceAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceAgentCreate'
      responses:
        '200':
          description: Replaced agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceAgentOut'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
components:
  parameters:
    AgentIdPath:
      name: agent_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: Voice agent ID.
  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'
        idle_nudges:
          $ref: '#/components/schemas/IdleNudgesConfig'
          nullable: true
        enable_interruptions:
          type: boolean
          default: true
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolCreate'
          default: []
        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: {}
        runtime_variables:
          type: array
          items:
            $ref: '#/components/schemas/RuntimeVariableDefinition'
          default: []
    VoiceAgentOut:
      type: object
      additionalProperties: false
      required:
        - id
        - organisation_id
        - name
        - system_prompt
        - greeting
        - language
        - region
        - models
        - idle_nudges
        - enable_interruptions
        - tools
        - 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'
        idle_nudges:
          $ref: '#/components/schemas/IdleNudgesConfig'
        enable_interruptions:
          type: boolean
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolOut'
        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
    UUID:
      type: string
      format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
    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.
    ToolCreate:
      oneOf:
        - title: Template tool
          description: Built-in call control tools (hangup, voicemail detection).
          allOf:
            - $ref: '#/components/schemas/TemplateTool'
        - title: Utility tool
          description: First-party utility tools such as current date/time lookup.
          allOf:
            - $ref: '#/components/schemas/BuiltInTool'
        - title: Webhook
          description: Call your backend via HTTP (LLM-invoked or system-triggered).
          allOf:
            - $ref: '#/components/schemas/WebhookToolCreate'
        - title: Human transfer
          description: >-
            Transfer the caller to a phone number (requires an outbound
            connection).
          allOf:
            - $ref: '#/components/schemas/HumanTransferTool'
      discriminator:
        propertyName: type
    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.
    ToolOut:
      oneOf:
        - title: Template tool
          allOf:
            - $ref: '#/components/schemas/TemplateToolOut'
        - title: Utility tool
          allOf:
            - $ref: '#/components/schemas/BuiltInTool'
        - title: Webhook
          allOf:
            - $ref: '#/components/schemas/WebhookToolOut'
        - title: Human transfer
          allOf:
            - $ref: '#/components/schemas/HumanTransferToolOut'
      discriminator:
        propertyName: type
    TemplateVariableMeta:
      type: object
      additionalProperties: true
      properties:
        required:
          type: boolean
        default:
          type: string
    DateTime:
      type: string
      format: date-time
      example: '2026-01-15T10:30:00Z'
    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
    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: []
    TemplateTool:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - template
      properties:
        type:
          type: string
          enum:
            - template
        id:
          $ref: '#/components/schemas/UUID'
        template:
          type: string
          enum:
            - hangup
            - voicemail_detection
        prompt:
          type: string
          nullable: true
          description: Optional override for the default tool prompt.
        execution_policy:
          $ref: '#/components/schemas/ToolExecutionPolicy'
    BuiltInTool:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - built_in
      properties:
        type:
          type: string
          enum:
            - built_in
        id:
          $ref: '#/components/schemas/UUID'
        built_in:
          type: string
          enum:
            - current_datetime
        source:
          type: string
          enum:
            - contextual
            - system
          default: contextual
          description: |
            - `contextual`: LLM-invoked tool
            - `system`: automatically triggered tool
        timezone:
          type: string
          default: UTC
          description: >-
            IANA timezone name or templated value that resolves to one at
            runtime.
        prompt:
          type: string
          maxLength: 500
          nullable: true
          description: >-
            Optional instructions override for the model or injected system
            context.
        system:
          $ref: '#/components/schemas/SystemToolConfig'
      description: |
        Configurable first-party utility tool.
        When `source=contextual`, `system` must be omitted.
        When `source=system`, `system` is required.
    WebhookToolCreate:
      type: object
      required:
        - type
        - id
        - name
        - description
        - url
        - parameters
      properties:
        type:
          type: string
          enum:
            - webhook
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: string
          maxLength: 64
          description: >
            Tool name. For `source=contextual`, use only letters, numbers,
            underscores, or dashes.

            Reserved names are not allowed (e.g. `end_call`,
            `detected_answering_machine`).
        description:
          type: string
          maxLength: 500
        llm_result_instructions:
          type: string
          maxLength: 2000
          nullable: true
          description: >-
            Static instructions for how the model should use successful webhook
            results. Does not support runtime personalization.
        url:
          type: string
          description: >-
            Webhook URL. Runtime personalization is allowed only in path
            segments and query parameter values. Scheme, host, port,
            credentials, fragments, and query parameter names must remain
            literal.
        parameters:
          type: object
          additionalProperties: true
          description: JSON Schema (object) for the tool parameters.
        auth:
          $ref: '#/components/schemas/WebhookToolAuthCreate'
        http_method:
          type: string
          enum:
            - POST
            - PUT
            - PATCH
            - DELETE
          default: POST
          description: HTTP method used when invoking the webhook.
        webhook_format:
          type: string
          enum:
            - envelope
            - raw
          default: envelope
          description: |
            - `envelope`: send SLNG metadata plus arguments in the request body
            - `raw`: send only the tool arguments object as the request body
        timeout_seconds:
          type: number
          minimum: 1
          maximum: 60
          default: 10
        wait_for_response:
          type: boolean
          default: true
        show_results_to_llm:
          type: boolean
          nullable: true
          description: >
            Defaults to `true` for contextual tools and `false` for system tools
            when omitted.
        source:
          type: string
          enum:
            - contextual
            - system
          default: contextual
          description: |
            - `contextual`: LLM-invoked tool (user-driven)
            - `system`: automatically triggered tool
        system:
          $ref: '#/components/schemas/SystemToolConfig'
        execution_policy:
          $ref: '#/components/schemas/ToolExecutionPolicy'
      description: >
        A webhook tool can be invoked in two ways:

        - `source=contextual` (LLM tool-calling). In this mode, `system` must be
        omitted.

        - `source=system` (automatic triggers). In this mode, `system` is
        required.


        Webhook secrets are write-only. When using bearer/hmac auth:

        - On create: `auth.token` / `auth.secret` is required.

        - On update: you can omit `auth.token` / `auth.secret` to keep the
        existing secret.
    HumanTransferTool:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - name
        - phone_number
      properties:
        type:
          type: string
          enum:
            - human_transfer
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: string
          maxLength: 64
          description: >
            Tool name. System webhook names may contain spaces; contextual
            webhook names must remain provider-safe.
        description:
          type: string
          maxLength: 500
          nullable: true
        phone_number:
          type: string
          description: >-
            Destination phone number. Can be a literal E.164 number or a
            templated value that resolves to E.164 at runtime.
        execution_policy:
          $ref: '#/components/schemas/ToolExecutionPolicy'
      description: >
        Transfers the caller to a human (requires an outbound connection on the
        agent).
    TemplateToolOut:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - template
      properties:
        type:
          type: string
          enum:
            - template
        id:
          $ref: '#/components/schemas/UUID'
        template:
          type: string
          enum:
            - hangup
            - voicemail_detection
        prompt:
          type: string
          nullable: true
        execution_policy:
          $ref: '#/components/schemas/ToolExecutionPolicy'
    WebhookToolOut:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - name
        - description
        - url
        - parameters
        - source
      properties:
        type:
          type: string
          enum:
            - webhook
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: string
          maxLength: 64
          pattern: ^[a-z_][a-z0-9_]*$
        description:
          type: string
          maxLength: 500
        llm_result_instructions:
          type: string
          maxLength: 2000
          nullable: true
          description: >-
            Static instructions for how the model should use successful webhook
            results. Does not support runtime personalization.
        url:
          type: string
          description: >-
            Webhook URL. Runtime personalization is allowed only in path
            segments and query parameter values. Scheme, host, port,
            credentials, fragments, and query parameter names must remain
            literal.
        parameters:
          type: object
          additionalProperties: true
        auth_type:
          type: string
          nullable: true
          description: Auth type (bearer/hmac). Secrets are write-only and never returned.
        http_method:
          type: string
          enum:
            - POST
            - PUT
            - PATCH
            - DELETE
          nullable: true
        webhook_format:
          type: string
          enum:
            - envelope
            - raw
          nullable: true
        timeout_seconds:
          type: number
          nullable: true
        wait_for_response:
          type: boolean
          nullable: true
        show_results_to_llm:
          type: boolean
          nullable: true
        source:
          type: string
          enum:
            - contextual
            - system
        system:
          $ref: '#/components/schemas/SystemToolConfig'
        execution_policy:
          $ref: '#/components/schemas/ToolExecutionPolicy'
    HumanTransferToolOut:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - name
        - phone_number
      properties:
        type:
          type: string
          enum:
            - human_transfer
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: string
          maxLength: 64
          pattern: ^[a-z_][a-z0-9_]*$
        description:
          type: string
          maxLength: 500
          nullable: true
        phone_number:
          type: string
          description: Phone number or templated value.
        execution_policy:
          $ref: '#/components/schemas/ToolExecutionPolicy'
    TtsFallbackModel:
      type: object
      additionalProperties: false
      required:
        - model
        - voice
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 200
        voice:
          type: string
          minLength: 1
          maxLength: 200
    ToolExecutionPolicy:
      type: object
      properties:
        pre_action_message:
          $ref: '#/components/schemas/PreActionMessagePolicy'
    SystemToolConfig:
      type: object
      additionalProperties: false
      required:
        - triggers
      properties:
        triggers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/SystemTrigger'
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/SystemArgumentRow'
          default: []
      description: Configuration for system-triggered webhook tools.
    WebhookToolAuthCreate:
      oneOf:
        - title: Bearer token auth
          description: 'Send an `Authorization: Bearer <token>` header.'
          allOf:
            - $ref: '#/components/schemas/WebhookToolAuthBearerCreate'
        - title: HMAC signature auth
          description: Send an `X-Signature-256` header (HMAC-SHA256 of the JSON body).
          allOf:
            - $ref: '#/components/schemas/WebhookToolAuthHmacCreate'
      discriminator:
        propertyName: type
    PreActionMessagePolicy:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        text:
          type: string
          maxLength: 500
          nullable: true
      description: >
        Optional "pre action" message behavior for tools.

        When enabled, `text` is required (except for the built-in `hangup`
        tool).

        This field is static configuration and does not support runtime
        personalization.
    SystemTrigger:
      type: object
      additionalProperties: false
      required:
        - event
      properties:
        event:
          $ref: '#/components/schemas/SystemEvent'
        source_tool_id:
          $ref: '#/components/schemas/UUID'
          nullable: true
      description: |
        For `tool_succeeded` and `tool_failed`, `source_tool_id` is required.
        For all other events, `source_tool_id` must be omitted.
    SystemArgumentRow:
      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: 500
          nullable: true
        source:
          $ref: '#/components/schemas/SystemArgumentSource'
    WebhookToolAuthBearerCreate:
      type: object
      additionalProperties: false
      required:
        - type
        - token
      properties:
        type:
          type: string
          enum:
            - bearer
        token:
          type: string
    WebhookToolAuthHmacCreate:
      type: object
      additionalProperties: false
      required:
        - type
        - secret
      properties:
        type:
          type: string
          enum:
            - hmac
        secret:
          type: string
    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
    SystemArgumentSource:
      oneOf:
        - title: Constant
          description: Use a fixed value.
          allOf:
            - $ref: '#/components/schemas/SystemArgumentSourceConstant'
        - title: Templated value
          description: >-
            Use a free-text value with `{{variable}}` placeholders resolved at
            tool execution time.
          allOf:
            - $ref: '#/components/schemas/SystemArgumentSourceTemplate'
        - title: Transcript excerpt
          description: Inject recent transcript messages (bounded by max messages/chars).
          allOf:
            - $ref: '#/components/schemas/SystemArgumentSourceTranscriptMessages'
        - title: Call context field
          description: >-
            Pull a field from the current call/session context (for example,
            call_id or other runtime metadata).
          allOf:
            - $ref: '#/components/schemas/SystemArgumentSourceSimple'
      discriminator:
        propertyName: type
    SystemArgumentSourceConstant:
      type: object
      additionalProperties: false
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - constant
        value: {}
    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
          maximum: 2000
          default: 200
    SystemArgumentSourceSimple:
      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
  responses:
    BadRequestError:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad-request:
              summary: Generic bad request
              value:
                detail: The request could not be processed.
    UnauthorizedError:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: Authentication failed
              value:
                detail: Authentication is required for this endpoint.
    ForbiddenError:
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            forbidden:
              summary: Access denied
              value:
                detail: You do not have access to this resource.
    NotFoundError:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found:
              summary: Resource not found
              value:
                detail: The requested resource was not found.
    ConflictError:
      description: Conflict.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            conflict:
              summary: Resource already exists or cannot be changed in current state
              value:
                detail: >-
                  The requested operation conflicts with the current resource
                  state.
    ValidationError:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation-error:
              summary: Request validation failed
              value:
                detail:
                  - loc:
                      - body
                      - language
                    msg: Input should be a valid string
                    type: string_type
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              summary: Unexpected application error
              value:
                detail: An unexpected internal error occurred.
    BadGatewayError:
      description: Bad gateway.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            upstream-failure:
              summary: Upstream provider or dispatcher failed
              value:
                detail: The upstream service failed to process the request.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````