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

# Create Agent

> Create a new draft agent.



## OpenAPI

````yaml /openapi.json post /v1/agents
openapi: 3.1.0
info:
  title: TurnCall
  description: Production voice agent platform API
  version: 0.1.0
servers: []
security: []
paths:
  /v1/agents:
    post:
      tags:
        - agents
      summary: Create Agent
      description: Create a new draft agent.
      operationId: create_agent_v1_agents_post
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Agent V1 Agents Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateAgentRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        environment:
          type: string
          pattern: ^(development|staging|production)$
          title: Environment
          default: development
        config:
          $ref: '#/components/schemas/AgentConfigSchema'
      type: object
      required:
        - name
      title: CreateAgentRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentConfigSchema:
      properties:
        pipeline_mode:
          type: string
          pattern: ^(cascade|s2s)$
          title: Pipeline Mode
          default: cascade
        system_prompt:
          type: string
          maxLength: 128000
          title: System Prompt
          default: ''
        first_message:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: First Message
        stt:
          $ref: '#/components/schemas/STTConfigSchema'
        llm:
          $ref: '#/components/schemas/LLMConfigSchema'
        tts:
          $ref: '#/components/schemas/TTSConfigSchema'
        language:
          type: string
          maxLength: 10
          title: Language
          default: en
        tools:
          items:
            $ref: '#/components/schemas/ToolDefinitionSchema'
          type: array
          title: Tools
        mcp_servers:
          items:
            $ref: '#/components/schemas/MCPServerSchema'
          type: array
          title: Mcp Servers
        guardrails:
          $ref: '#/components/schemas/GuardrailsSchema'
        analysis:
          $ref: '#/components/schemas/AnalysisSchema'
        silence_timeout_ms:
          type: integer
          maximum: 5000
          minimum: 200
          title: Silence Timeout Ms
          default: 800
        interruption_enabled:
          type: boolean
          title: Interruption Enabled
          default: true
        smart_turn_detection:
          type: boolean
          title: Smart Turn Detection
          description: Use ML-based turn detection (SmartTurnV3)
          default: true
        smart_turn_stop_secs:
          type: number
          maximum: 10
          minimum: 0.5
          title: Smart Turn Stop Secs
          description: Max silence before forcing end-of-turn
          default: 1
        max_call_duration_seconds:
          type: integer
          maximum: 14400
          minimum: 60
          title: Max Call Duration Seconds
          default: 3600
        voicemail_detection:
          $ref: '#/components/schemas/VoicemailDetectionSchema'
        s2s:
          $ref: '#/components/schemas/S2SConfigSchema'
        avatar:
          $ref: '#/components/schemas/AvatarConfigSchema'
        transport:
          type: string
          pattern: ^(twilio|webrtc|both)$
          title: Transport
          default: twilio
        server_url:
          $ref: '#/components/schemas/ServerUrlConfigSchema'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      additionalProperties: false
      type: object
      title: AgentConfigSchema
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    STTConfigSchema:
      properties:
        provider:
          type: string
          title: Provider
          default: deepgram
        model:
          type: string
          title: Model
          default: nova-3
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          default: en
        extra:
          additionalProperties: true
          type: object
          title: Extra
      type: object
      title: STTConfigSchema
    LLMConfigSchema:
      properties:
        provider:
          type: string
          title: Provider
          default: openai
        model:
          type: string
          title: Model
          default: gpt-4o-mini
        temperature:
          type: number
          maximum: 2
          minimum: 0
          title: Temperature
          default: 0.7
        max_tokens:
          type: integer
          maximum: 128000
          minimum: 1
          title: Max Tokens
          default: 1024
        base_url:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
          title: Base Url
        api_key:
          anyOf:
            - type: string
              maxLength: 512
            - type: 'null'
          title: Api Key
        fallback_models:
          items:
            type: string
          type: array
          title: Fallback Models
        extra:
          additionalProperties: true
          type: object
          title: Extra
      type: object
      title: LLMConfigSchema
    TTSConfigSchema:
      properties:
        provider:
          type: string
          title: Provider
          default: deepgram
        model:
          type: string
          title: Model
          default: aura-2-helena-en
        voice:
          type: string
          title: Voice
          default: aura-2-helena-en
        speed:
          type: number
          maximum: 4
          minimum: 0.25
          title: Speed
          default: 1
        extra:
          additionalProperties: true
          type: object
          title: Extra
      type: object
      title: TTSConfigSchema
    ToolDefinitionSchema:
      properties:
        name:
          type: string
          maxLength: 128
          minLength: 1
          pattern: ^[a-z_][a-z0-9_]*$
          title: Name
        description:
          type: string
          maxLength: 1024
          minLength: 1
          title: Description
        parameters_schema:
          additionalProperties: true
          type: object
          title: Parameters Schema
        execution_mode:
          type: string
          pattern: ^(sync|async)$
          title: Execution Mode
          default: sync
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
        webhook_secret:
          anyOf:
            - type: string
              maxLength: 256
              minLength: 16
            - type: 'null'
          title: Webhook Secret
        timeout_seconds:
          type: integer
          maximum: 300
          minimum: 1
          title: Timeout Seconds
          default: 10
        max_retries:
          type: integer
          maximum: 5
          minimum: 0
          title: Max Retries
          default: 1
      type: object
      required:
        - name
        - description
      title: ToolDefinitionSchema
    MCPServerSchema:
      properties:
        name:
          type: string
          maxLength: 128
          minLength: 1
          pattern: ^[a-z_][a-z0-9_-]*$
          title: Name
        transport:
          type: string
          pattern: ^(http|sse|stdio)$
          title: Transport
          default: http
        url:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
          title: Url
          description: Server URL (required for http/sse transport)
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: Custom headers sent with requests (e.g. Authorization)
        command:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Command
          description: Executable command (required for stdio transport)
        args:
          items:
            type: string
          type: array
          title: Args
          description: Command arguments (stdio transport)
        env:
          additionalProperties:
            type: string
          type: object
          title: Env
          description: Environment variables for subprocess (stdio transport)
        timeout_seconds:
          type: integer
          maximum: 60
          minimum: 1
          title: Timeout Seconds
          description: Connection timeout
          default: 10
        tool_filter:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tool Filter
          description: Only expose these tools (None = all tools)
      type: object
      required:
        - name
      title: MCPServerSchema
      description: MCP server connection configuration.
    GuardrailsSchema:
      properties:
        max_tool_calls_per_turn:
          type: integer
          maximum: 20
          minimum: 1
          title: Max Tool Calls Per Turn
          default: 5
        prohibited_topics:
          items:
            type: string
          type: array
          title: Prohibited Topics
        extra:
          additionalProperties: true
          type: object
          title: Extra
      type: object
      title: GuardrailsSchema
    AnalysisSchema:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: true
        summary_enabled:
          type: boolean
          title: Summary Enabled
          default: true
        summary_prompt:
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
          title: Summary Prompt
          description: Custom prompt for summary generation
        success_evaluation:
          $ref: '#/components/schemas/SuccessEvaluationSchema'
        sentiment_enabled:
          type: boolean
          title: Sentiment Enabled
          default: false
        structured_extraction_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Structured Extraction Schema
          description: JSON Schema for structured data extraction from transcript
        scoring_rubric:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Scoring Rubric
          description: Custom scoring rubric with named criteria
        takeaway_ids:
          items:
            type: string
          type: array
          maxItems: 20
          title: Takeaway Ids
          description: >-
            Takeaways (reusable structured outputs) to extract after each call;
            results keyed by takeaway name in analysis.takeaways
        model:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Model
          description: 'LLM model override for analysis (default: agent''s LLM model)'
        extra:
          additionalProperties: true
          type: object
          title: Extra
      type: object
      title: AnalysisSchema
      description: Post-call analysis configuration. Results ship inline in `call.ended`.
    VoicemailDetectionSchema:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        voicemail_message:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Voicemail Message
          description: TTS message to leave on voicemail
        backoff_plan:
          $ref: '#/components/schemas/VoicemailBackoffSchema'
          description: 'Retry plan: re-classify periodically until confident'
        beep_max_await_seconds:
          type: number
          maximum: 30
          minimum: 1
          title: Beep Max Await Seconds
          description: Max time to wait for beep after voicemail detected
          default: 5
        voicemail_expected_duration_seconds:
          type: number
          maximum: 60
          minimum: 5
          title: Voicemail Expected Duration Seconds
          description: Expected voicemail greeting length
          default: 15
        custom_system_prompt:
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
          title: Custom System Prompt
          description: Custom classifier prompt
      type: object
      title: VoicemailDetectionSchema
      description: Voicemail detection for outbound calls.
    S2SConfigSchema:
      properties:
        provider:
          type: string
          title: Provider
          default: openai
        model:
          type: string
          title: Model
          default: gpt-4o-realtime-preview
        voice:
          type: string
          title: Voice
          default: alloy
        turn_detection:
          type: string
          pattern: ^(server_vad|pipecat_vad)$
          title: Turn Detection
          default: server_vad
        base_url:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
          title: Base Url
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
        max_tokens:
          anyOf:
            - type: integer
              maximum: 128000
              minimum: 1
            - type: 'null'
          title: Max Tokens
        extra:
          additionalProperties: true
          type: object
          title: Extra
      type: object
      title: S2SConfigSchema
      description: Speech-to-speech model configuration.
    AvatarConfigSchema:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        provider:
          type: string
          pattern: ^(heygen|tavus)$
          title: Provider
          default: heygen
        avatar_id:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Avatar Id
        is_sandbox:
          type: boolean
          title: Is Sandbox
          default: true
        replica_id:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Replica Id
        persona_id:
          type: string
          maxLength: 256
          title: Persona Id
          default: pipecat-stream
      type: object
      title: AvatarConfigSchema
      description: Video avatar config (WebRTC + cascade only). HeyGen or Tavus.
    ServerUrlConfigSchema:
      properties:
        url:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
          title: Url
        secret:
          anyOf:
            - type: string
              maxLength: 128
            - type: 'null'
          title: Secret
        timeout_seconds:
          type: number
          maximum: 30
          minimum: 1
          title: Timeout Seconds
          default: 5
        events:
          items:
            type: string
          type: array
          title: Events
      type: object
      title: ServerUrlConfigSchema
      description: Server URL for server events.
    SuccessEvaluationSchema:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        rubric:
          type: string
          maxLength: 4000
          title: Rubric
          description: Criteria for the LLM to judge success
          default: ''
        scale:
          type: string
          pattern: ^(pass_fail|likert|numeric)$
          title: Scale
          description: pass_fail | likert (1-5) | numeric (0-100)
          default: pass_fail
      type: object
      title: SuccessEvaluationSchema
      description: Defines how to evaluate call success.
    VoicemailBackoffSchema:
      properties:
        max_retries:
          type: integer
          maximum: 10
          minimum: 0
          title: Max Retries
          default: 3
        start_at_seconds:
          type: number
          maximum: 30
          minimum: 1
          title: Start At Seconds
          default: 5
        frequency_seconds:
          type: number
          maximum: 15
          minimum: 1
          title: Frequency Seconds
          default: 3
      type: object
      title: VoicemailBackoffSchema

````