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

# Get list of AI models

> Retrieves AI models with optional filtering. Two response shapes:

- **Paginated mode (default):** Returns `{ success, data, total, hasMore, page, pageSize, message }`. The `institution` field on each item is populated to `{ name, ainame, picture }`.
- **Minimum mode (`minimum: true`):** Returns `{ success, data, message }` with `data` projected to `{ _id, name, model_use, status }`. No pagination fields. Used by dropdown selectors.

Filter precedence: `institution` > `account` (space-separated IDs, expanded to their institutions and filtered by the caller's RAP) > caller's own institution (for admins) > all non-deleted models (for supers).




## OpenAPI

````yaml /mdx/api-reference/admin/admin-api.json post /api/admin/aimodels
openapi: 3.0.0
info:
  title: Pria Admin API
  version: 2.0.1
  description: >-
    Pria API Documentation Praxis's developer platform is a core part of our
    mission to empower organizations to grow better. Our APIs are designed to
    enable teams of any shape or size to build robust integrations that help
    them customize and get the most value out of Pria. All Pria APIs are built
    using REST conventions and designed to have a predictable URL structure.
    <br/>  <br/>They use many standard HTTP features, including methods (POST,
    GET, PUT, DELETE) and error response codes.  <br/> <br/>All API calls are
    made under https://hiimpria.ai/api and all responses return standard JSON.
    In these docs, you'll find lists of all available endpoints for a given API,
    along with interactive code blocks for building requests. For walkthroughs
    of basic usage for these APIs, check out the API guides.
servers:
  - url: https://pria.praxislxp.com
    description: Pria API Server
security: []
tags:
  - name: Authentication
    description: User authentication, registration, and password management (/api/auth)
  - name: OAuth
    description: OAuth authentication providers - Google, GitHub, SSO (/api/auth/oauth)
  - name: User
    description: User profile management and account operations (/api/user)
  - name: User Institutions
    description: User institution memberships and switching (/api/user/institution)
  - name: User Tools
    description: Available tools for authenticated users (/api/user/tools)
  - name: Institutions
    description: Institution settings and configuration (/api/user/institution)
  - name: Conversation
    description: AI conversation and Q&A endpoints (/api/ai)
  - name: Realtime
    description: Real-time voice AI and WebRTC sessions (/api/ai/rt)
  - name: Assistant
    description: AI assistant configuration and management (/api/user/assistant)
  - name: History
    description: Conversation history and favorites (/api/user/history)
  - name: RAG
    description: >-
      Document upload, embedding, and retrieval-augmented generation
      (/api/user/files, /api/user/rag)
  - name: Setting
    description: Instance variables and settings management (/api/user/setting)
  - name: Branding
    description: Digital twin branding and customization (/api/agent/branding)
  - name: Agent
    description: Agent engagement and session management (/api/agent)
  - name: SDK Launch
    description: >-
      SDK launch token signing and verification for secure iframe embedding
      (/api/auth/sdk-sign, /api/auth/sdk-verify)
  - name: Testing
    description: Health checks, diagnostics, and test endpoints (/api/test)
  - name: Admin Accounts
    description: Account management for super admins (/api/admin/account)
  - name: Admin Institutions
    description: Institution management for admins (/api/admin/institution)
  - name: Admin Users
    description: User management for admins (/api/admin/user)
  - name: Admin Entitlements
    description: >-
      User-institution relationships and permissions
      (/api/admin/userInstitution)
  - name: Admin Sessions
    description: Session management for admins (/api/admin/session)
  - name: Admin Histories
    description: Conversation history management and analytics (/api/admin/history)
  - name: Admin Assistants
    description: AI assistant management for admins (/api/admin/assistant)
  - name: Admin Questions
    description: Institution question and prompt management (/api/admin/question)
  - name: Admin Tools
    description: Tool configuration management (/api/admin/tool)
  - name: Admin AI Models
    description: AI model configuration (/api/admin/aimodel)
  - name: Admin MCP Servers
    description: Model Context Protocol server management (/api/admin/mcpserver)
  - name: Admin Feedbacks
    description: User feedback management (/api/admin/feedback)
  - name: Admin Uploads
    description: Upload management (/api/admin/upload)
  - name: Admin Charts
    description: Analytics and visualization chart management (/api/admin/chart)
  - name: Admin Memory
    description: Admin inspection and editing of user/instance memory parameters.
  - name: Admin Usage Limits
    description: Per-user usage-vs-cap reporting and account-wide at-limit counts.
paths:
  /api/admin/aimodels:
    post:
      tags:
        - Admin AI Models
      summary: Get list of AI models
      description: >
        Retrieves AI models with optional filtering. Two response shapes:


        - **Paginated mode (default):** Returns `{ success, data, total,
        hasMore, page, pageSize, message }`. The `institution` field on each
        item is populated to `{ name, ainame, picture }`.

        - **Minimum mode (`minimum: true`):** Returns `{ success, data, message
        }` with `data` projected to `{ _id, name, model_use, status }`. No
        pagination fields. Used by dropdown selectors.


        Filter precedence: `institution` > `account` (space-separated IDs,
        expanded to their institutions and filtered by the caller's RAP) >
        caller's own institution (for admins) > all non-deleted models (for
        supers).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIModelListRequest'
      responses:
        '200':
          description: >-
            AI models retrieved successfully. Shape depends on the `minimum`
            flag in the request.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AIModelListResponse'
                  - $ref: '#/components/schemas/AIModelListMinimumResponse'
        '400':
          description: Query / RAP check failure.
        '401':
          description: Authentication required.
        '403':
          description: Caller is not an admin or super user.
      security:
        - apiKeyAuth: []
components:
  schemas:
    AIModelListRequest:
      type: object
      properties:
        institution:
          type: string
          description: >-
            Filter by institution ID. When omitted, admins fall back to their
            own institution and supers see all.
        account:
          type: string
          description: >-
            Filter by account IDs (space-separated). Resolves to every
            non-deleted institution under those accounts, then filters by the
            caller's RAP.
        minimum:
          type: boolean
          description: >-
            When true, returns a flat list of `{ _id, name, model_use, status }`
            with no pagination. Used by dropdown selectors.
        page:
          type: integer
          minimum: 1
          default: 1
          description: Page number (1-based, ignored when minimum=true).
        pageSize:
          type: integer
          minimum: 1
          maximum: 5000
          default: 100
          description: >-
            Page size (also accepted as `limitsearch`; ignored when
            minimum=true).
    AIModelListResponse:
      type: object
      description: Paginated response (returned when `minimum` is false or omitted).
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/AIModel'
        total:
          type: integer
          description: Total number of matching AI models.
        hasMore:
          type: boolean
          description: Whether more results are available.
        page:
          type: integer
          description: Current page number.
        pageSize:
          type: integer
          description: Number of results per page.
        message:
          type: string
    AIModelListMinimumResponse:
      type: object
      description: >-
        Minimum-mode response (returned when `minimum=true`). No pagination
        fields; `data` items are projected to `{ _id, name, model_use, status
        }`.
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
              name:
                type: string
              model_use:
                type: string
              status:
                type: string
        message:
          type: string
    AIModel:
      type: object
      properties:
        _id:
          type: string
          description: AI Model ID
        name:
          type: string
          description: >-
            Model name (unique per institution + model_use). For example, the
            published model identifier sent to the provider (e.g. "gpt-4o",
            "claude-sonnet-4-5").
        institution:
          oneOf:
            - type: string
              description: Institution ID (when unpopulated).
            - type: object
              description: >-
                Populated institution summary (when listed via GET-by-id or
                paginated list).
              properties:
                _id:
                  type: string
                name:
                  type: string
                ainame:
                  type: string
                picture:
                  type: string
        model_use:
          type: string
          enum:
            - conversationModel
            - imageGenerationModel
            - audioGenerationModel
            - videoGenerationModel
            - imageAnalysisModel
            - embeddingsModel
            - audioAnalysisModel
            - videoAnalysisModel
            - ttsModel
            - summaryModel
            - rtModel
            - moderationModel
          default: conversationModel
          description: Functional role this model plays in the dispatch pipeline.
        description:
          type: string
          default: ''
          description: Free-form description of the model.
        api_url:
          type: string
          description: >-
            Base URL of the provider endpoint. Required for openai_cli custom
            models; optional/ignored for bedrock_cli.
          example: https://api.openai.com/v1
        api_key:
          type: string
          description: >-
            Provider API key. Required for openai_cli, mistral_cli, and xai_cli
            custom models. Not required for bedrock_cli (uses AWS credentials).
        default_headers:
          type: object
          additionalProperties:
            type: string
          description: >-
            Optional flat string-string map of extra HTTP request headers passed
            verbatim on every call. Useful for OpenAI-compatible proxies that
            require an API-version header (Cohere, Azure, some LiteLLM setups).
            Currently honored by the openai_cli client builder.
        client_library:
          type: string
          enum:
            - openai_cli
            - anthropic_cli
            - bedrock_cli
            - google_cli
            - mistral_cli
            - xai_cli
            - stability_cli
          default: openai_cli
          description: SDK / dispatch backend used to talk to the provider.
        features:
          $ref: '#/components/schemas/AIModelFeatures'
        input_media:
          $ref: '#/components/schemas/AIModelInputMedia'
        output_media:
          $ref: '#/components/schemas/AIModelOutputMedia'
        max_input_tokens:
          type: integer
          default: 128000
          description: Maximum input (context) tokens supported by the model.
        max_output_tokens:
          type: integer
          default: 64000
          description: Maximum output tokens the model will emit in a single response.
        reasoning_effort:
          type: string
          enum:
            - none
            - low
            - medium
            - high
            - max
          nullable: true
          default: null
          description: >-
            Default reasoning-effort hint passed to providers that accept it
            (e.g. OpenAI o-series, xAI grok-3-mini).
        extended_context:
          type: boolean
          default: false
          description: Whether the model's extended-context tier is enabled.
        status:
          type: string
          enum:
            - active
            - inactive
            - deleted
          default: active
          description: >-
            Lifecycle status. Deletes are soft — name is prefixed with the
            timestamp and status flipped to "deleted".
        picture_url:
          type: string
          description: Optional avatar / icon URL shown in the admin UI.
        created:
          type: string
          format: date-time
          description: Creation timestamp
    AIModelFeatures:
      type: object
      description: Capability flags advertised by the model.
      properties:
        stream:
          type: boolean
          default: false
          description: Supports streaming responses.
        tools:
          type: boolean
          default: false
          description: Supports tool / function calling.
        code:
          type: boolean
          default: false
          description: Supports a built-in code-execution tool.
        vision:
          type: boolean
          default: false
          description: Supports image inputs.
        mcp:
          type: boolean
          default: false
          description: Supports Model Context Protocol tool servers.
    AIModelInputMedia:
      type: object
      description: Input modalities the model accepts.
      properties:
        text:
          type: boolean
          default: true
        image:
          type: boolean
          default: false
        audio:
          type: boolean
          default: false
        video:
          type: boolean
          default: false
        pdf:
          type: boolean
          default: false
    AIModelOutputMedia:
      type: object
      description: Output modalities the model can produce.
      properties:
        text:
          type: boolean
          default: true
        audio:
          type: boolean
          default: false
        video:
          type: boolean
          default: false
        image:
          type: boolean
          default: false
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-access-token
      description: JWT token passed in x-access-token header

````