> ## 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, including its complete shared tool and MCP attachment lists.



## 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: 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/{agent_id}:
    parameters:
      - $ref: '#/components/parameters/AgentIdPath'
    put:
      tags:
        - Agents
      summary: Replace agent
      description: >-
        Replace a voice agent, including its complete shared tool and MCP
        attachment lists.
      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'
        '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':
          $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'
        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.
    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.
    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.
    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.
    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: []
    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'
  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

````