---
title: "Create an ExternalModel"
method: POST
path: "/api/v1/externalmodel"
tags: ["externalmodels"]
---

# Create an ExternalModel

`POST /api/v1/externalmodel`

Creates a new ExternalModel and its companion MaaSModelRef.

## Request body

- CreateExternalModelRequest
  - `name` string, required
  - `namespace` string, required
  - `displayName` string — Optional human-readable display name (openshift.io/display-name annotation)
  - `description` string — Optional description (openshift.io/description annotation)
  - `modelName` string
  - `providerRefs` ProviderRef[], required
    - `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

## Response `201`

ExternalModel created

## Changes

- **2026-08-31** `f8bfb089642f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/changes/api/v1/externalmodel/post.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)