> ## 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.

# Retrieve list of institutions

> Get a list of all institutions with their details and statistics



## OpenAPI

````yaml /mdx/api-reference/admin/admin-api.json post /api/admin/institutions
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/institutions:
    post:
      tags:
        - Admin Institutions
      summary: Retrieve list of institutions
      description: Get a list of all institutions with their details and statistics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstitutionListRequest'
            example:
              minimum: true
      responses:
        '200':
          description: Successfully retrieved institutions list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstitutionListResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '500':
          description: Internal server error
      security:
        - apiKeyAuth: []
components:
  schemas:
    InstitutionListRequest:
      type: object
      properties:
        minimum:
          type: boolean
          description: Whether to return minimal institution data (bypasses pagination)
        compact:
          type: boolean
          description: Whether to return compact institution data
        account:
          type: string
          description: Account ID(s) to filter institutions (space-separated for multiple)
        institutionsearch:
          type: string
          description: Search term for institutions (matches name, AI name, publicId)
        statusFilter:
          type: string
          enum:
            - active
            - inactive
            - all
          default: active
          description: >-
            Filter institutions by lifecycle status. 'active' returns only
            active instances, 'inactive' returns only inactive, 'all' returns
            both. Deleted institutions are always excluded.
        activeOnly:
          type: boolean
          default: false
          description: >-
            When true, restrict to instances that have actually been used
            (lastActivityAt is set, not null). ANDs with statusFilter.
        withCustomModel:
          type: boolean
          default: false
          description: >-
            When true, restrict to institutions that have a non-empty
            conversationModel set. Combines with statusFilter and notPoolCredits
            via AND.
        notPoolCredits:
          type: boolean
          default: false
          description: >-
            When true, restrict to institutions where poolCredits is not true
            (i.e. false or unset). Combines with statusFilter and
            withCustomModel via AND.
        hasThreats:
          type: boolean
          default: false
          description: >-
            When true, narrow the RAP-scoped result to institutions that have
            threat incidents (intersection with distinct
            threatMonitoringIncident.institutionIds). Backs the Praxis Shield
            panel's instance selector; only ever narrows the scoped set.
        page:
          type: integer
          minimum: 1
          default: 1
          description: Page number (1-based)
        pageSize:
          type: integer
          minimum: 1
          maximum: 5000
          default: 100
          description: Number of results per page
        limitsearch:
          type: number
          description: 'DEPRECATED: Use pageSize instead'
          deprecated: true
    InstitutionListResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        data:
          type: array
          items:
            $ref: '#/components/schemas/Institution'
          description: Array of institution objects
        total:
          type: integer
          description: Total number of matching institutions
        hasMore:
          type: boolean
          description: Whether more results are available beyond the current page
        page:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of results per page
        message:
          type: string
          description: Response message
    Institution:
      type: object
      properties:
        _id:
          type: string
          description: Institution ID
        name:
          type: string
          description: Institution name
        picture:
          type: string
          description: Institution picture URL
          format: uri
        credits:
          type: integer
          description: Available credits for the institution
        creditsUsed:
          type: integer
          description: Number of credits used
        creditsAwarded:
          type: integer
          description: Credits awarded to the institution
        status:
          type: string
          enum:
            - active
            - inactive
          description: Institution status
        publicId:
          type: string
          description: Public identifier for the institution
        publicAuthorizedUrls:
          type: array
          items:
            type: string
          description: List of authorized URLs for the institution
        ainame:
          type: string
          description: AI name for the institution
        contactEmail:
          type: string
          description: Contact email for the institution
        poolCredits:
          type: boolean
          description: Whether credits are pooled
        created:
          type: string
          format: date-time
          description: Institution creation timestamp
        lastActivityAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp of the most recent activity (history save) cascaded from
            users. Null if no activity has been recorded.
        conversationModel:
          type: string
          description: AI conversation model used
        account:
          $ref: '#/components/schemas/Account'
        agent:
          $ref: '#/components/schemas/AgentWorkspaceAgentState'
          nullable: true
          description: >-
            Agent workspace desired-state configuration for this institution,
            when activation has been requested.
        maxCompletionTokens:
          type: integer
          description: Maximum completion tokens allowed
        creditsTotal:
          type: number
          description: Total credits available
          nullable: true
        creditsUsagePct:
          type: number
          description: Percentage of credits used
        id:
          type: string
          description: Institution ID
        displayAgentDetails:
          type: boolean
          description: Whether to display persisted tool details on saved History records
        displayThinkingDetails:
          type: boolean
          description: >-
            Whether to display persisted model thinking/reasoning details on
            saved History records
        displayRagSearchDetails:
          type: boolean
          description: >-
            Whether to display persisted RAG/KAG retrieval segments on saved
            History records
        displayThinkingExecution:
          type: boolean
          description: >-
            Whether to display the live thinking trace while a response is
            streaming
        displayToolExecution:
          type: boolean
          description: >-
            Whether to display live tool execution indicators while a response
            is streaming
    Account:
      type: object
      properties:
        _id:
          type: string
          description: Account ID
        name:
          type: string
          description: Account name
        managerEmail:
          type: string
          format: email
          description: Email of the account's primary manager (required).
        credits:
          type: integer
          description: Account credits.
        domainUrls:
          type: array
          items:
            type: string
          description: Domains associated with the account.
        status:
          type: string
          enum:
            - active
            - inactive
            - deleted
          description: Account status. Soft-delete sets this to `deleted`.
        qualification:
          type: string
          description: Sales pipeline qualification (Suspect, Prospect, MQL, SQL, …).
        created:
          type: string
          format: date-time
          description: Creation timestamp
        creditCaps:
          type: object
          description: Per-user credit caps (super-only). Disabled by default.
          properties:
            enabled:
              type: boolean
              default: false
            perUserAccountTotal:
              type: number
              nullable: true
            perUserInstitutionDefault:
              type: number
              nullable: true
            perUser24hDefault:
              type: number
              nullable: true
    AgentWorkspaceAgentState:
      type: object
      properties:
        enabled:
          type: boolean
        status:
          type: string
          enum:
            - not_enabled
            - requested
            - provisioning
            - ready
            - failed
            - disabled
        preset:
          type: string
        manifestYaml:
          type: string
        manifestDigest:
          type: string
        preferences:
          $ref: '#/components/schemas/AgentWorkspacePreferences'
        requestedBy:
          type: string
        requestedAt:
          type: string
          format: date-time
        provisionedAt:
          type: string
          format: date-time
        lastError:
          type: string
    AgentWorkspacePreferences:
      type: object
      properties:
        cpu:
          type: number
          minimum: 0.25
          maximum: 4
        memoryMb:
          type: integer
          minimum: 512
          maximum: 8192
        storageGb:
          type: integer
          minimum: 5
          maximum: 100
        gui:
          type: boolean
        vncResolution:
          type: string
          example: 1280x800
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-access-token
      description: JWT token passed in x-access-token header

````