---
title: "List ExternalModels"
method: GET
path: "/api/v1/externalmodel"
tags: ["externalmodels"]
---

# List ExternalModels

`GET /api/v1/externalmodel`

Returns ExternalModels enriched with referenced ExternalProvider details and companion MaaSModelRef endpoint status.

## Query parameters

- `namespace` string, required

## Response `200`

ExternalModel list

- object
  - `data` ExternalModelSummary[]
    - `name` string
    - `namespace` string
    - `displayName` string — Human-readable display name (from openshift.io/display-name annotation)
    - `description` string — Description (from openshift.io/description annotation)
    - `modelName` string
    - `providerRefs` ProviderRef[]
      - `providerName` string, required
      - `weight` integer, required — Relative traffic proportion. 0 disables the ref. Defaults to 1 if omitted on the CR.
      - `apiFormat` string, required
      - `path` string, required
      - `targetModel` string, required
      - `config` object — Optional model-provider binding configuration (externalProviderRefs[].config)
      - `authMechanism` 'apikey' | 'sigv4' | 'oauth2' — Auth type override from the ExternalModel providerRef (overrides ExternalProvider auth)
      - `credentialSecretRef` string — Secret name override from the ExternalModel providerRef (overrides ExternalProvider auth.secretRef)
      - `provider` ExternalProviderDetails — ExternalProvider fields not present on the ExternalModel providerRef
        - `displayName` string
        - `description` string
        - `endpointUrl` string — FQDN of the external provider with no scheme or path (e.g. api.openai.com)
        - `authMechanism` 'apikey' | 'sigv4' | 'oauth2'
        - `credentialSecretRef` string — Name of the Secret holding provider credentials (spec.auth.secretRef.name)
        - `provider` string — Provider identifier (spec.provider)
        - `config` object
        - `phase` string
        - `statusMessage` string — Human-readable status message from the Ready condition in status.conditions
        - `reason` string — Reason from the Ready condition in status.conditions
    - `phase` string
    - `statusMessage` string — Human-readable status message from the Ready condition in status.conditions
    - `reason` string — Reason from the Ready condition in status.conditions
    - `maaSModelRef` ExternalModelMaaSModelRefStatus — Companion MaaSModelRef status (list response only)
      - `phase` string
      - `statusMessage` string — Human-readable status message from the Ready condition in status.conditions
      - `reason` string — Reason from the Ready condition in status.conditions
      - `endpoint` string — Published MaaS endpoint URL (status.endpoint)
      - `governanceAttached` boolean — True when the companion MaaSModelRef has status.conditions type=GovernanceAttached with status=True (active subscription + auth policy pairing).

## Changes

- **2026-08-31** `f8bfb089642f` — 1 breaking, 1 info
  - the `data/items/providerRefs/items/weight` response property's min was decreased from `1.00` to `0.00` for the response status `200`
  - the `data/items/providerRefs/items/provider/endpointUrl` response's property pattern `^[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?)+$` was added for the status `200`
- **2026-08-06** `9112415ceeca` — 3 info
  - added the optional property `data/items/maaSModelRef/reason` to the response with the `200` status
  - added the optional property `data/items/providerRefs/items/provider/reason` to the response with the `200` status
  - added the optional property `data/items/reason` to the response with the `200` status
- **2026-08-05** `e3208dd1f079` — 2 info
  - added the optional property `data/items/providerRefs/items/authMechanism` to the response with the `200` status
  - added the optional property `data/items/providerRefs/items/credentialSecretRef` to the response with the `200` status
- **2026-07-17** `23490bfeeebf` — 2 info
  - added the optional property `data/items/maaSModelRef/governanceAttached` to the response with the `200` status
  - added the optional property `data/items/providerRefs/items/provider/credentialSecretRef` to the response with the `200` status
- **2026-07-10** `a7f523a6836e` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/changes/api/v1/externalmodel/get.md)

---

[API](https://skmtc.dev/opendatahub-io/apis/maas-bff-api.md) · [All operations](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opendatahub-io/maas-bff-api/revisions/f8bfb089642f/schema)