# Model Providers and Base Models

## Read Current State

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  "$GATEWAY_BASE_URL/api/admin/catalog/providers"

curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  "$GATEWAY_BASE_URL/api/admin/catalog/base-models"
```

Public read-only catalog endpoints also exist at `/api/v1/public/catalog/providers` and `/api/v1/public/catalog/base-models`.

## Provider Catalog

Create a provider:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "providerKey": "example-openai",
    "code": "example-openai",
    "displayName": "Example OpenAI Compatible",
    "providerType": "openai",
    "defaultBaseUrl": "https://api.example.com/v1",
    "defaultAuthType": "APIKey",
    "source": "gateway",
    "capabilitySchema": {},
    "defaultRateLimitPolicy": {},
    "metadata": {"protocol": "openai-compatible"},
    "status": "active"
  }' \
  "$GATEWAY_BASE_URL/api/admin/catalog/providers"
```

Use `PATCH /api/admin/catalog/providers/{providerID}` with the complete current provider body to update. `providerType` selects the runtime client through the platform candidate. Common supported values include `openai`, `gemini`, `volces`, `keling`, `minimax`, and `universal`. Unknown types may fall back to the OpenAI client, so never leave a custom integration type ambiguous.

Delete with `DELETE /api/admin/catalog/providers/{providerID}` only after checking platform references and obtaining confirmation.

## Base Model

Create a base model after its provider exists:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "providerKey": "example-openai",
    "canonicalModelKey": "example-openai:example-chat",
    "providerModelName": "example-chat",
    "modelType": ["text_generate"],
    "modelAlias": "example-chat",
    "displayName": "Example Chat",
    "capabilities": {
      "text_generate": {
        "supportedApiProtocols": ["openai_chat_completions"]
      }
    },
    "baseBillingConfig": {
      "textInputPer1k": 0.001,
      "textOutputPer1k": 0.002
    },
    "defaultRateLimitPolicy": {},
    "runtimePolicyOverride": {},
    "metadata": {"description": "Example OpenAI-compatible chat model"},
    "catalogType": "custom",
    "defaultSnapshot": {},
    "pricingVersion": 1,
    "status": "active"
  }' \
  "$GATEWAY_BASE_URL/api/admin/catalog/base-models"
```

Use `PATCH /api/admin/catalog/base-models/{baseModelID}` with a complete body to update. Do not omit capabilities, billing, policy bindings, metadata, or status unintentionally.

Reset endpoints are destructive:

- `POST /api/admin/catalog/base-models/{baseModelID}/reset`
- `POST /api/admin/catalog/base-models/reset-all`

Only system-seeded models with default snapshots can be reset. Delete with `DELETE /api/admin/catalog/base-models/{baseModelID}` only after checking platform-model bindings.