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

# Get agent

> Get a single voice agent by ID.



## OpenAPI

````yaml /api-reference/agents/agents.oas.yaml get /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'
    get:
      tags:
        - Agents
      summary: Get agent
      description: Get a single voice agent by ID.
      operationId: getAgent
      responses:
        '200':
          description: Agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceAgentOut'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    AgentIdPath:
      name: agent_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: Voice agent ID.
  schemas:
    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.
    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
    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.
    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: []
    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'
    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.
    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.
    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'
    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:
    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.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````