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

# List models

> The live catalog, one entry per served model, with context windows, capabilities, and supported parameters.

This is the OpenAI-compatible model list, extended with per-model metadata. It's the machine-readable companion to [Choosing a model](/docs/models.md), poll it if your application selects models dynamically or wants to feature-detect before sending a request.

> [!NOTE]
>
> Treat `context_length`, `max_output_length`, `supported_sampling_parameters`, and the `reasoning` block as the source of truth for request limits and reasoning behavior, they change when the catalog changes, without a docs release.


## OpenAPI

````yaml /openapi/inference.yaml get /models
openapi: 3.1.0
info:
  title: Pearl Inference API
  version: '1.0'
  description: >-
    The data-plane API your applications call to run models: OpenAI- and
    Anthropic-compatible endpoints behind one base URL.
servers:
  - url: https://inference.pearlresearch.ai/v1
security:
  - inferenceKey: []
paths:
  /models:
    get:
      summary: List models
      description: >-
        The live catalog, one entry per served model, with context windows,
        capabilities, and supported parameters.
      operationId: listModels
      responses:
        '200':
          description: The catalog.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
              examples:
                catalog:
                  summary: Catalog
                  value:
                    pricing_source: registry
                    data:
                      - id: zai-org/GLM-5.3
                        hugging_face_id: zai-org/GLM-5.3
                        name: 'Z.AI: GLM-5.3'
                        created: 1787640170
                        description: >-
                          GLM-5.3 is a text mixture-of-experts model supporting
                          tool use, structured output, and low, high, or maximum
                          reasoning effort.
                        input_modalities:
                          - text
                        output_modalities:
                          - text
                        quantization: fp4
                        context_length: 1000000
                        max_output_length: 1000000
                        pricing:
                          prompt: …
                          completion: …
                          input_cache_read: …
                        supported_sampling_parameters:
                          - temperature
                          - top_p
                          - top_k
                          - frequency_penalty
                          - presence_penalty
                          - stop
                          - seed
                          - max_tokens
                        supported_features:
                          - tools
                          - json_mode
                          - reasoning
                        reasoning:
                          default_effort: max
                          default_enabled: true
                          mandatory: true
                          supported_efforts:
                            - low
                            - high
                            - max
                          supports_max_tokens: false
        '401':
          $ref: '#/components/responses/ModelsUnauthorized'
        '403':
          $ref: '#/components/responses/WrongRegion'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
      security:
        - inferenceKey: []
        - xApiKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl https://inference.pearlresearch.ai/v1/models \
              -H "Authorization: Bearer $PEARL_API_KEY"
components:
  headers:
    X-Request-ID:
      description: >-
        The request ID. Send your own UUID in `X-Request-ID` to use it as the
        ID. Include the ID when you contact support.
      schema:
        type: string
      example: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
  schemas:
    ModelList:
      type: object
      properties:
        data:
          type: array
          description: One entry per served model, with the fields below.
          items:
            $ref: '#/components/schemas/Model'
        pricing_source:
          type: string
          enum:
            - registry
            - partial
          description: >-
            `registry` when every listed model has a price for your
            organization, `partial` when some don't (their entries omit
            `pricing`).
    Model:
      type: object
      properties:
        id:
          type: string
          description: The value you pass as `model` in requests.
        name:
          type: string
          description: Human-readable display name (also used in the dashboard).
        hugging_face_id:
          type: string
          description: The upstream open-weight checkpoint the deployment serves.
        created:
          type: integer
          description: Unix timestamp of the model's release.
        input_modalities:
          type: array
          description: >-
            What the model accepts, `text`, plus `image` on vision models. Check
            this before sending multimodal content.
          items:
            type: string
            enum:
              - text
              - image
        output_modalities:
          type: array
          description: All catalog models output text.
          items:
            type: string
        quantization:
          type: string
          enum:
            - fp4
            - fp8
            - int8
          description: >-
            Serving precision (`fp4`, `fp8`, `int8`), a property of this
            deployment, not the checkpoint.
        context_length:
          type: integer
          description: Maximum tokens (prompt + response) per request.
        max_output_length:
          type: integer
          description: >-
            Ceiling for generated tokens, the effective upper bound for
            `max_tokens`.
        pricing:
          type: object
          description: >-
            Your organization's rates as USD-per-token strings: `prompt`,
            `completion`, and `input_cache_read` (the discounted cached-input
            rate, when the model has one). Omitted for a model without a price
            for your organization. The dashboard
            [Models](https://platform.pearlresearch.ai/models) page shows the
            same rates per million tokens.
          properties:
            prompt:
              type: string
            completion:
              type: string
            input_cache_read:
              type: string
        supported_sampling_parameters:
          type: array
          description: >-
            The authoritative per-model list of accepted sampling parameters
            (e.g. whether `min_p` is available).
          items:
            type: string
        supported_features:
          type: array
          description: >-
            Capability flags: `tools`, `json_mode`, `reasoning`. The [model
            guide](/models) documents verified capability per model.
          items:
            type: string
            enum:
              - tools
              - json_mode
              - reasoning
        reasoning:
          type: object
          description: Per-model reasoning metadata.
          properties:
            supported_efforts:
              type: array
              description: >-
                The set of effort levels the model actually serves. A request
                for any other level is still accepted and rounds up to the next
                served level, or to the highest one when it asks for more, so
                this list, not the request schema, is the real menu. `none` is
                the disable control, not a rung.
              items:
                type: string
            default_effort:
              type: string
              description: >-
                What omitting the request control gets you (GLM-5.3 defaults to
                `max`).
            mandatory:
              type: boolean
              description: >-
                `true` marks models that always think and reject the disable
                with `400` (GLM-5.3, GLM-5.3-Flash).
            supports_max_tokens:
              type: boolean
              description: >-
                Whether a `reasoning.max_tokens` thinking budget is accepted; it
                is `false` on every model today, and the budget returns `400`,
                see [Reasoning models](/reasoning).
        description:
          type: string
          description: >-
            A short human-readable summary of the model, safe to display to
            users.
        deprecation_date:
          type: string
          description: >-
            When the model is scheduled for retirement, present only once one is
            set. See [Model deprecation](/deprecation).
        datacenters:
          type: array
          description: >-
            Where the model is served, as `{"country_code": …}` entries, when
            known.
          items:
            type: object
            properties:
              country_code:
                type: string
    OpenAIError:
      type: object
      description: Errors are JSON in OpenAI's shape, with the request ID in the body.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - api_error
            code:
              type: string
              description: >-
                Present only when set, for example `model_not_found` or
                `no_capacity`.
            request_id:
              type: string
              description: The request ID.
  responses:
    ModelsUnauthorized:
      description: Missing, unknown, revoked, or expired API key.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            unknownKey:
              summary: Unknown API key
              value:
                error:
                  message: unknown API key
                  type: authentication_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    WrongRegion:
      description: >-
        Wrong endpoint for your organization's [inference
        region](/data-residency).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            wrongRegion:
              summary: Wrong endpoint for the region
              value:
                error:
                  message: wrong endpoint for your organization's inference region
                  type: permission_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    CatalogUnavailable:
      description: The catalog is temporarily unavailable. Retry with backoff.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            catalogUnavailable:
              summary: Catalog unavailable
              value:
                error:
                  message: the catalog is temporarily unavailable
                  type: api_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
  securitySchemes:
    inferenceKey:
      type: http
      scheme: bearer
      description: >-
        `Bearer` followed by an inference API key (`sk-prl-infapi-`). Create
        keys on the [API Keys](https://platform.pearlresearch.ai/api-keys) page.
        Management keys (`sk-prl-mgmt-`) cannot call models.
    xApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your inference API key. Send this or `Authorization`; if you send both,
        they must carry the same key.

````

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