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

# Create Agent

> Creates a new agent. Choose from Pipeline (voice + text), Realtime (lowest latency), or Text (chat only) architecture.



## OpenAPI

````yaml POST /v1/agents
openapi: 3.1.0
info:
  title: TalkifAI API
  version: 1.0.0
  description: Build and manage AI voice and chat agents programmatically.
servers:
  - url: https://api.talkifai.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create and manage voice and chat agents
  - name: Voice Calls
    description: Initiate outbound calls and retrieve call data
  - name: Text Chat
    description: Text chat sessions via REST + SSE
  - name: Batch Calling
    description: Run large-scale outbound call campaigns
paths:
  /v1/agents:
    post:
      tags:
        - Agents
      summary: Create Agent
      description: |-
        Creates a new agent in your organization.

        **Architecture-specific required fields:**
        - `pipeline`: `model` + `stt` required
        - `realtime`: `realtimeProvider` required (`openai` or `gemini`)
        - `text`: `model` required
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - description
                - sysMsg
              properties:
                name:
                  type: string
                  example: Customer Support Bot
                description:
                  type: string
                  example: Handles tier-1 support queries
                sysMsg:
                  type: string
                  example: You are a helpful customer support agent.
                agentArchitecture:
                  type: string
                  enum:
                    - pipeline
                    - realtime
                    - text
                  default: pipeline
                model:
                  type: string
                  example: gpt_4o_mini
                  description: Required for pipeline and text
                stt:
                  type: string
                  example: deepgram
                  description: Required for pipeline
                voiceId:
                  type: string
                  example: gemini-leda-en
                  description: Defaults to gemini-leda-en for pipeline if omitted
                realtimeProvider:
                  type: string
                  enum:
                    - openai
                    - gemini
                  description: Required for realtime
                greetingType:
                  type: string
                  enum:
                    - agentFirst
                    - userFirst
                  default: agentFirst
                greetingMessage:
                  type: string
                  example: Hello! How can I help you today?
                temperature:
                  type: number
                  default: 0.7
                  minimum: 0
                  maximum: 2
                inactivityTimeout:
                  type: integer
                  default: 30
                  minimum: 10
                  maximum: 60
                mode:
                  type: string
                  enum:
                    - public
                    - private
                    - commercial
                  default: public
                languages:
                  type: array
                  items:
                    type: string
                  example:
                    - english
                functionCallingEnabled:
                  type: boolean
                  default: false
                enabledFunctions:
                  type: array
                  items:
                    type: string
                  default: []
                enabledCustomFunctions:
                  type: array
                  items:
                    type: string
                  default: []
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      agent:
                        $ref: '#/components/schemas/Agent'
        '400':
          description: Missing required fields or validation error
        '401':
          description: Invalid or missing API key
      security:
        - apiKeyHeader: []
components:
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          example: 5b710eca-ee67-4c3a-aeb6-8b541f451b40
        name:
          type: string
          example: Customer Support Bot
        description:
          type: string
          nullable: true
          example: Handles tier-1 support queries
        agentArchitecture:
          type: string
          enum:
            - pipeline
            - realtime
            - text
          example: pipeline
        model:
          type: string
          nullable: true
          example: gpt_4o_mini
          description: >-
            LLM model. Set for pipeline and text architectures; null for
            realtime.
        stt:
          type: string
          nullable: true
          example: deepgram
          description: >-
            Speech-to-text provider. Set for pipeline; null for realtime and
            text.
        voiceId:
          type: string
          nullable: true
          example: gemini-leda-en
          description: >-
            TTS voice ID. Required for pipeline; optional for realtime (used
            only when greetingType is agentFirst).
        realtimeProvider:
          type: string
          nullable: true
          example: openai
          description: >-
            Realtime provider. Set for realtime architecture; null for pipeline
            and text.
        sysMsg:
          type: string
          nullable: true
          example: >-
            You are a helpful customer support agent for Acme Corp. Be concise
            and friendly.
        greetingType:
          type: string
          enum:
            - agentFirst
            - userFirst
          example: agentFirst
          description: Controls who speaks first when the call connects.
        greetingMessage:
          type: string
          nullable: true
          example: Hello! How can I help you today?
          description: >-
            Opening message spoken by the agent. Only used when greetingType is
            agentFirst.
        temperature:
          type: number
          example: 0.7
          description: LLM sampling temperature (0–2).
        inactivityTimeout:
          type: integer
          example: 30
          description: >-
            Seconds of user silence before the agent ends the call. Range:
            10–60.
        lastMessage:
          type: string
          nullable: true
          example: Is there anything else I can help you with?
          description: Final message spoken by the agent before ending the call.
        mode:
          type: string
          enum:
            - public
            - private
            - commercial
          example: public
          description: >-
            Visibility mode. public: all org members. private: creator +
            admins/owners only. commercial: globally accessible.
        functionCallingEnabled:
          type: boolean
          example: false
        enabledFunctions:
          type: array
          items:
            type: string
          description: IDs of built-in functions enabled for this agent.
        enabledCustomFunctions:
          type: array
          items:
            type: string
          description: IDs of custom (webhook) functions enabled for this agent.
        languages:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              language:
                type: string
                example: en
          description: Languages the agent is configured to support.
        userId:
          type: string
          description: ID of the user who created this agent.
        organizationId:
          type: string
          description: ID of the organization this agent belongs to.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tk_live_...
      description: Your TalkifAI API key. Get it from Studio → Settings → API Keys.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your TalkifAI API key. Generate from Studio → Settings → API Keys.
        Format: `tk_live_...`

````