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

# List LLM models

> List the LLM models you can use in an agent. Use a model's `llm_model_id` as `llm.llm_id` when you [create](/api-reference/ai-agents-v3/create-ai-agent) or [update](/api-reference/ai-agents-v3/update-ai-agent) an agent.

The catalog holds the platform's built-in models plus the custom models of your organization. A model can be used only if its `status` is `ACTIVE` and its `llm_type` array contains the agent's `llm_type` (`simple` or `flow`).

## Filters

| Parameter | Notes |
| --- | --- |
| `llm_model_ids` | Restrict to specific ids. Repeat the parameter or pass a comma-separated list. |
| `language_code` | Models that support these language codes. Repeatable. |
| `status` | `ACTIVE`, `INACTIVE` or `DELETED`. Defaults to `ACTIVE`. |
| `model_type` | `builtIn` or `custom`. |
| `model_provider` | Provider key, for example `openai`. |
| `sort_direction` | `asc` or `desc`. |

Results are paged with a cursor. Pass `data.next_page_token` back as `page_token`. When it is absent, you have reached the last page. A `page_size` outside `1`–`100` or an unknown `sort_direction` returns `422`.

The response uses the v3 envelope: `status` (lowercase), `message` and `data`, with the models in `data.items`. List items include every field, with explicit `null`s.



## OpenAPI

````yaml /api-reference/openapi.json get /v2/llm-models
openapi: 3.1.0
info:
  title: Verbex Platform API
  description: API for managing AI agents, calls, phone numbers, and more.
  version: 1.0.0
servers: []
security: []
tags:
  - name: Knowledge Bases
    description: >-
      Create and manage knowledge bases, ingest documents into them, and search
      them semantically.


      **Authentication.** Every request carries a bearer token: `Authorization:
      Bearer <API_TOKEN>`. That is the only credential a client sends. The
      gateway resolves your identity from it and injects the tenant headers the
      service reads internally, so clients never send `x-user-org-id` or
      `x-verbex-id` themselves.


      **Tenancy is enforced on every route.** A knowledge base belongs to one
      organization and one user. Requesting one your token does not own returns
      `404 Knowledge base not found`, never `403`. This is deliberate: a
      nonexistent ID, a malformed ID and someone else's ID are indistinguishable
      in the response, so the API cannot be used to probe for other tenants'
      data. If you get a `404` on an ID you are certain exists, suspect the
      token before you suspect the ID.


      **Ingestion is asynchronous.** File upload and website crawl both answer
      `202` as soon as the material is stored and the job is queued. Parsing,
      chunking, embedding and indexing happen afterwards in a worker. Poll the
      document status endpoint until it reports `completed` before expecting
      search to see the content. That gap is the most common source of "why
      isn't my data showing up".


      **There is no document update endpoint.** Every submission mints a new
      `document_id`, so re-uploading a file or re-crawling the same URLs creates
      a second document while the first remains. To refresh material, delete
      then resubmit — and note that the sequence is not atomic.
  - name: AI Agents v3
    description: >-
      Create, read, update and delete AI agents. v3 selects the LLM,
      speech-to-text model and voice by catalog id, and wraps every response in
      a standard envelope. It replaces the deprecated AI Agents v2 operations,
      which stop working on November 30, 2026. See [Migrate from v2 to
      v3](/api-reference/ai-agents-v3/migrate-from-v2).
  - name: LLM Models
    description: >-
      The LLM model catalog. Look up the `llm_model_id` to send as `llm.llm_id`
      when you create or update an agent.
  - name: Speech Providers
    description: >-
      The speech-to-text and text-to-speech provider catalogs. Look up the
      `provider_id`, `model_id` and `voice_id` to send when you create or update
      an agent.
paths:
  /v2/llm-models:
    get:
      tags:
        - LLM Models
      summary: List LLM models
      description: >-
        List the LLM models you can use in an agent. Use a model's
        `llm_model_id` as `llm.llm_id` when you
        [create](/api-reference/ai-agents-v3/create-ai-agent) or
        [update](/api-reference/ai-agents-v3/update-ai-agent) an agent.


        The catalog holds the platform's built-in models plus the custom models
        of your organization. A model can be used only if its `status` is
        `ACTIVE` and its `llm_type` array contains the agent's `llm_type`
        (`simple` or `flow`).


        ## Filters


        | Parameter | Notes |

        | --- | --- |

        | `llm_model_ids` | Restrict to specific ids. Repeat the parameter or
        pass a comma-separated list. |

        | `language_code` | Models that support these language codes.
        Repeatable. |

        | `status` | `ACTIVE`, `INACTIVE` or `DELETED`. Defaults to `ACTIVE`. |

        | `model_type` | `builtIn` or `custom`. |

        | `model_provider` | Provider key, for example `openai`. |

        | `sort_direction` | `asc` or `desc`. |


        Results are paged with a cursor. Pass `data.next_page_token` back as
        `page_token`. When it is absent, you have reached the last page. A
        `page_size` outside `1`–`100` or an unknown `sort_direction` returns
        `422`.


        The response uses the v3 envelope: `status` (lowercase), `message` and
        `data`, with the models in `data.items`. List items include every field,
        with explicit `null`s.
      operationId: list_llm_models_v2
      parameters:
        - name: llm_model_ids
          in: query
          required: false
          description: Restrict the result to these model ids.
          schema:
            type: array
            items:
              type: string
            title: Llm Model Ids
        - name: language_code
          in: query
          required: false
          description: Only models that support these language codes.
          schema:
            type: array
            items:
              type: string
            title: Language Code
        - name: status
          in: query
          required: false
          description: Filter by lifecycle status.
          schema:
            type: string
            enum:
              - ACTIVE
              - INACTIVE
              - DELETED
            default: ACTIVE
            title: Status
        - name: model_type
          in: query
          required: false
          description: Built-in platform models or your organization's custom models.
          schema:
            type: string
            enum:
              - builtIn
              - custom
            title: Model Type
        - name: model_provider
          in: query
          required: false
          description: Filter by provider key.
          schema:
            type: string
            title: Model Provider
        - name: sort_direction
          in: query
          required: false
          description: Sort order. Any other value returns `422`.
          schema:
            type: string
            enum:
              - asc
              - desc
            title: Sort Direction
        - name: page_size
          in: query
          required: false
          description: Number of results per page, `1`–`100`.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            title: Page Size
        - name: page_token
          in: query
          required: false
          description: >-
            Cursor from the previous response's `next_page_token`. Omit for the
            first page.
          schema:
            type: string
            title: Page Token
      responses:
        '200':
          description: Page of LLM models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseLlmModelPage'
              example:
                status: success
                message: LLM models retrieved successfully
                data:
                  items:
                    - llm_model_id: 9d259647-d5ec-423d-96a9-2750980e8ecb
                      llm_type:
                        - simple
                        - flow
                      model_provider: openai
                      provider_display_name: OpenAI
                      model_name: gpt-4o-mini
                      model_type: builtIn
                      model_display_name: GPT-4o mini
                      language_code:
                        - en-US
                        - ja-JP
                      model_description: Fast, low-cost general-purpose model.
                      is_realtime_model: false
                      pca_enabled: true
                      latency_in_ms: 600
                      tag: null
                      max_tokens: 4096
                      model_temperature: 0.7
                      priority: 10
                      organization_id: null
                      workspace_id: null
                      created_by_user_id: usr_admin01
                      modified_by_user_id: usr_admin01
                      created_at: '2026-05-04T08:00:00Z'
                      modified_at: '2026-09-12T11:20:00Z'
                      status: ACTIVE
                  next_page_token: >-
                    eyJwcmlvcml0eSI6MTAsIl9pZCI6IjY4YzFmMGExZTRiMGEyYzNkNGU1ZjZhNyJ9
        '422':
          description: A query parameter is out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponse'
              examples:
                page_size:
                  summary: '`page_size` outside 1–100'
                  value:
                    status: error
                    message: Page size must be between 1 and 100
                sort_direction:
                  summary: Unknown `sort_direction`
                  value:
                    status: error
                    message: 'Invalid sort direction: up'
components:
  schemas:
    ApiResponseLlmModelPage:
      type: object
      title: ApiResponse<Page<LlmModel>>
      properties:
        status:
          type: string
          enum:
            - success
            - error
          title: Status
          description: 'Outcome of the request: `success` or `error`, in lowercase.'
        message:
          type: string
          title: Message
          description: Human-readable message about the result.
        data:
          $ref: '#/components/schemas/LlmModelPage'
          description: One page of LLM models.
    V3ErrorResponse:
      type: object
      title: ErrorResponse
      properties:
        status:
          type: string
          enum:
            - error
          title: Status
          description: 'Outcome of the request: `success` or `error`, in lowercase.'
        message:
          type: string
          title: Message
          description: Human-readable message about the result.
        error_details:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Error Details
          description: >-
            Field path to message, for validation failures. Omitted when there
            are none.
    LlmModelPage:
      type: object
      title: Page<LlmModel>
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LlmModel'
          title: Items
          description: Models on this page.
        next_page_token:
          type: string
          title: Next Page Token
          description: Cursor for the following page. Omitted on the last page.
    LlmModel:
      type: object
      title: LlmModel
      description: >-
        An LLM model in the catalog. List items include every field, with
        explicit `null`s.
      properties:
        llm_model_id:
          type: string
          title: Llm Model Id
          description: >-
            Catalog id. Send it as `llm.llm_id` when you create or update an
            agent.
        llm_type:
          type: array
          items:
            type: string
            enum:
              - simple
              - agentic
              - flow
          title: Llm Type
          description: >-
            Agent types this model supports. It must contain the agent's
            `llm_type`.
        model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Provider
          description: Provider key, for example `openai`.
        provider_display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider Display Name
          description: Provider name for display.
        model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Name
          description: Provider model name, for example `gpt-4o-mini`.
        model_type:
          anyOf:
            - type: string
              enum:
                - builtIn
                - custom
            - type: 'null'
          title: Model Type
          description: >-
            `builtIn` for platform models, `custom` for models your organization
            added.
        model_display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Display Name
          description: Model name for display.
        language_code:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Language Code
          description: Language codes the model supports.
        model_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Description
          description: Description of the model.
        is_realtime_model:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Realtime Model
          description: Whether the model is a realtime model.
        pca_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Pca Enabled
          description: Whether the model can run post-call analysis.
        latency_in_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency In Ms
          description: Expected latency in milliseconds.
        tag:
          anyOf:
            - type: string
            - type: 'null'
          title: Tag
          description: Optional label for grouping.
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
          description: Maximum tokens per response.
        model_temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Model Temperature
          description: >-
            Default temperature. A new agent that omits `model_temperature`
            takes this value.
        priority:
          anyOf:
            - type: integer
            - type: 'null'
          title: Priority
          description: Sort weight. Higher numbers appear first.
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: Owning organization of a custom model.
        workspace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Id
          description: Owning workspace of a custom model.
        created_by_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By User Id
          description: User who created the model.
        modified_by_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Modified By User Id
          description: User who last changed the model.
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Creation time.
        modified_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Modified At
          description: Last change time.
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - DELETED
          title: Status
          description: >-
            Lifecycle status. Only `ACTIVE` models can be referenced by an
            agent.
      required:
        - llm_model_id

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.