elevenlabs Agents API

openapi: 3.2.0
info:
  title: ElevenLabs Conversational AI Agents API
  description: The ElevenLabs Conversational AI API enables developers to build interactive voice agents that can engage in natural, real-time conversations. It provides REST endpoints for managing agents, conversations, knowledge bases, tools, and phone number integrations. The API supports multi-turn dialogue across 70+ languages and is designed for building customer service agents, voice assistants, and interactive voice response systems.
  version: '1.0'
  contact:
    name: ElevenLabs Support
    url: https://help.elevenlabs.io
  termsOfService: https://elevenlabs.io/terms-of-service
servers:
- url: https://api.elevenlabs.io
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Agents
  description: Endpoints for creating, managing, and configuring conversational AI agents with voice capabilities.
paths:
  /v1/convai/agents:
    get:
      operationId: listAgents
      summary: List agents
      description: Returns a list of all conversational AI agents and their metadata for the authenticated account.
      tags:
      - Agents
      parameters:
      - name: page_size
        in: query
        required: false
        description: Number of agents to return per page.
        schema:
          type: integer
          default: 30
      - name: cursor
        in: query
        required: false
        description: Pagination cursor for retrieving the next page of results.
        schema:
          type: string
      responses:
        '200':
          description: List of agents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListResponse'
        '401':
          description: Unauthorized - invalid or missing API key
    post:
      operationId: createAgent
      summary: Create agent
      description: Creates a new conversational AI agent from a configuration object specifying the agent's behavior, voice, language model, and available tools.
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '200':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Bad request - invalid configuration
        '401':
          description: Unauthorized - invalid or missing API key
        '422':
          description: Unprocessable entity - validation error
  /v1/convai/agents/{agent_id}:
    get:
      operationId: getAgent
      summary: Get agent
      description: Retrieves the full configuration and metadata for a specific conversational AI agent.
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/agentId'
      responses:
        '200':
          description: Agent configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Agent not found
    patch:
      operationId: updateAgent
      summary: Update agent
      description: Updates the configuration of an existing conversational AI agent. Only the provided fields are updated; unspecified fields retain their current values.
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/agentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Bad request - invalid configuration
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Agent not found
    delete:
      operationId: deleteAgent
      summary: Delete agent
      description: Deletes a conversational AI agent and all its associated configuration. This action is irreversible.
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/agentId'
      responses:
        '200':
          description: Agent deleted successfully
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Agent not found
  /v1/convai/agents/{agent_id}/simulate:
    post:
      operationId: simulateConversation
      summary: Simulate conversation
      description: Runs a simulated conversation between the agent and a simulated user for testing purposes. Returns the full conversation transcript and evaluation metrics.
      tags:
      - Agents
      parameters:
      - $ref: '#/components/parameters/agentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateConversationRequest'
      responses:
        '200':
          description: Simulation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationResult'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Agent not found
components:
  schemas:
    CreateAgentRequest:
      type: object
      required:
      - conversation_config
      properties:
        name:
          type: string
          description: Display name for the agent.
        conversation_config:
          $ref: '#/components/schemas/ConversationConfig'
        metadata:
          type: object
          description: Additional metadata for the agent.
          additionalProperties:
            type: string
    AgentResponse:
      type: object
      properties:
        agent_id:
          type: string
          description: The identifier of the agent.
    SimulateConversationRequest:
      type: object
      properties:
        simulated_user_config:
          type: object
          description: Configuration for the simulated user in the test conversation.
          properties:
            prompt:
              type: string
              description: Instructions defining the simulated user's behavior.
            first_message:
              type: string
              description: The initial message from the simulated user.
        max_turns:
          type: integer
          description: Maximum number of conversation turns for the simulation.
          minimum: 1
    SimulationResult:
      type: object
      properties:
        conversation_id:
          type: string
          description: Identifier for the simulated conversation.
        transcript:
          type: array
          description: Full transcript of the simulated conversation.
          items:
            type: object
            properties:
              role:
                type: string
                description: The speaker role in the conversation.
                enum:
                - agent
                - user
              message:
                type: string
                description: The spoken message content.
    ConversationConfig:
      type: object
      description: Configuration defining the agent's conversational behavior, voice settings, and language model parameters.
      properties:
        agent:
          type: object
          description: Agent behavior configuration.
          properties:
            prompt:
              type: object
              description: The system prompt and instructions for the agent.
              properties:
                prompt:
                  type: string
                  description: The system instructions that define agent behavior.
            first_message:
              type: string
              description: The initial message the agent sends when a conversation starts.
            language:
              type: string
              description: The primary language for the agent.
        tts:
          type: object
          description: Text-to-speech configuration for the agent's voice.
          properties:
            voice_id:
              type: string
              description: The voice to use for the agent's speech output.
            model_id:
              type: string
              description: The TTS model to use.
        stt:
          type: object
          description: Speech-to-text configuration for processing user input.
          properties:
            model_id:
              type: string
              description: The STT model to use for transcription.
        llm:
          type: object
          description: Language model configuration for conversation generation.
          properties:
            model_id:
              type: string
              description: The language model to use.
            temperature:
              type: number
              description: Controls randomness in the model's responses.
              minimum: 0
              maximum: 2
    UpdateAgentRequest:
      type: object
      properties:
        name:
          type: string
          description: Updated display name for the agent.
        conversation_config:
          $ref: '#/components/schemas/ConversationConfig'
        metadata:
          type: object
          description: Updated metadata for the agent.
          additionalProperties:
            type: string
    AgentSummary:
      type: object
      properties:
        agent_id:
          type: string
          description: Unique identifier for the agent.
        name:
          type: string
          description: Display name of the agent.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the agent was created.
    Agent:
      type: object
      properties:
        agent_id:
          type: string
          description: Unique identifier for the agent.
        name:
          type: string
          description: Display name of the agent.
        conversation_config:
          $ref: '#/components/schemas/ConversationConfig'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the agent was created.
        metadata:
          type: object
          description: Additional metadata associated with the agent.
          additionalProperties:
            type: string
    AgentListResponse:
      type: object
      properties:
        agents:
          type: array
          description: List of agents.
          items:
            $ref: '#/components/schemas/AgentSummary'
        has_more:
          type: boolean
          description: Whether there are more agents available.
        next_cursor:
          type: string
          description: Cursor for retrieving the next page.
  parameters:
    agentId:
      name: agent_id
      in: path
      required: true
      description: The unique identifier of the conversational AI agent.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: xi-api-key
      description: ElevenLabs API key passed in the xi-api-key header for authentication.
externalDocs:
  description: ElevenLabs Conversational AI Documentation
  url: https://elevenlabs.io/docs/overview/capabilities/conversational-ai