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

# List Agent Versions

> Retrieve a history of all saved configurations (versions) for a specific agent.

Retrieve a complete history of all configurations (versions) for a specific Voice Agent.

Every time you update an agent's settings—whether changing its LLM, modifying its prompt, or attaching a new tool—a new version is saved. This endpoint allows you to audit those changes or fetch older configurations.

<Info>
  **Authentication Required:** You must include your API key in the `x-api-key` header to authenticate this request.
</Info>

### Required Parameters

You must pass the target agent's unique identifier in the URL.

* **`agentId`:** The 24-character string ID of the agent whose version history you want to retrieve.

### Understanding the Response

The API returns an array of `versions` belonging to the agent. Each object in this array represents a distinct snapshot in time:

* **`version_id`**: A unique UUID for this specific configuration state.
* **`active`**: A boolean flag (`true` or `false`). Only **one** version can be active at a time. The active version is the one currently used when initiating a new LiveKit session.
* **`config`**: The full configuration dictionary (prompts, models, avatars, tools) exactly as it existed when this version was saved.
* **`created_at`**: The timestamp of when this version was generated.

### Common Use Cases

1. **Auditing/Debugging:** If an agent suddenly starts behaving unexpectedly, you can list versions to compare the current `active: true` config against older, stable versions.
2. **Rollback Preparation:** By fetching the `version_id` of an older, successful configuration, you can prepare your application to rollback or activate that previous state.


## OpenAPI

````yaml get /agents/{agentId}/versions
openapi: 3.0.3
info:
  title: Lyzr Voice LiveKit API
  version: 1.0.0
servers:
  - url: https://voice-livekit.studio.lyzr.ai/v1
security: []
paths:
  /agents/{agentId}/versions:
    get:
      summary: List Agent Versions
      description: >-
        Retrieve a history of all saved configurations (versions) for a specific
        agent.
      parameters:
        - name: agentId
          in: path
          required: true
          description: The unique identifier of the agent.
          schema:
            type: string
            example: 1bca24a70cf2e9fb0c722a35
      responses:
        '200':
          description: Agent version list retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id:
                    type: string
                    example: 1bca24a70cf2e9fb0c722a35
                  versions:
                    type: array
                    items:
                      type: object
                      properties:
                        version_id:
                          type: string
                          example: ffffffff-ffff-ffff-ffff-ffffffffffff
                        config:
                          $ref: '#/components/schemas/AgentConfig'
                        active:
                          type: boolean
                          example: true
                        created_at:
                          type: string
                          example: '2023-10-25T12:00:00Z'
        '400':
          description: Invalid agent ID format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  issues:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  example:
                    type: object
                    additionalProperties: true
        '404':
          description: Agent not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: string
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AgentConfig:
      type: object
      description: Comprehensive configuration settings for the agent.
      properties:
        agent_name:
          type: string
        agent_description:
          type: string
        engine:
          type: object
          properties:
            kind:
              type: string
            stt:
              type: string
            llm:
              type: string
            tts:
              type: string
            voice_id:
              type: string
            language:
              type: string
        engine_pipeline:
          type: object
        engine_realtime:
          type: object
        prompt:
          type: string
        agent_role:
          type: string
        agent_goal:
          type: string
        agent_instructions:
          type: string
        dynamic_variables:
          type: object
          additionalProperties:
            type: string
        dynamic_variable_defaults:
          type: object
          additionalProperties:
            type: string
        conversation_start:
          type: object
          properties:
            who:
              type: string
            greeting:
              type: string
        turn_detection:
          type: string
        noise_cancellation:
          type: object
        api_key:
          type: string
        knowledge_base:
          type: object
        managed_agents:
          type: object
        tools:
          type: array
          items:
            type: string
        lyzr_tools:
          type: array
          items:
            type: object
        agent_id:
          type: string
        user_id:
          type: string
        session_id:
          type: string
        preemptive_generation:
          type: boolean
        pronunciation_correction:
          type: boolean
        pronunciation_rules:
          type: object
        audio_recording_enabled:
          type: boolean
        vad_enabled:
          type: boolean
        avatar:
          type: object
        background_audio:
          type: object
        corrections:
          type: array
          items:
            type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````