Models API

Model listing and provider management endpoints. ZERG aggregates models from all configured providers and serves a unified catalog.

Overview

The models API provides read access to the model catalog (pricing, capabilities, context windows) and CRUD for provider configurations. The model catalog is sourced from a static JSON file (models.json) merged with user overrides.

Authentication

All endpoints require Authorization: Bearer <token>. Provider management endpoints require admin role.

Endpoints

List Models

GET /api/v1/models

Returns all available models with pricing and capability metadata.

{
  "ok": true,
  "data": [
    {
      "id": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "mode": "chat",
      "context_window": 200000,
      "pricing": {
        "input": 3.00,
        "output": 15.00,
        "currency": "USD",
        "unit": "MTok"
      },
      "capabilities": ["tools", "thinking", "vision", "prompt_caching"],
      "status": "available"
    }
  ]
}

Get Model Details

GET /api/v1/models/:id

Returns detailed information for a single model.

List Providers

GET /api/v1/providers

Returns configured provider instances and their health status.

{
  "ok": true,
  "data": [
    {
      "name": "anthropic",
      "type": "anthropic",
      "status": "healthy",
      "models": ["claude-sonnet-4-20250514"],
      "circuit_breaker": "closed"
    }
  ]
}

Provider Health Check

GET /api/v1/providers/:name/health

Returns per-adapter health check results, cached for 60 seconds.

Create Provider

POST /api/v1/providers

Request Body:

{
  "name": "my-provider",
  "type": "openai_compat",
  "base_url": "https://api.example.com/v1",
  "api_key": "sk-...",
  "models": ["custom-model-1"]
}

Update Provider

PUT /api/v1/providers/:name

Update provider configuration. Returns updated provider object.

Delete Provider

DELETE /api/v1/providers/:name

Remove a provider configuration. Models served by this provider will no longer be available.

Error Codes:

Code	Description
400	Invalid provider configuration
401	Authentication required
403	Admin role required for mutations
404	Model or provider not found

Examples:

curl http://127.0.0.1:11434/api/v1/models \
  -H "Authorization: Bearer $TOKEN"

curl http://127.0.0.1:11434/api/v1/providers/anthropic/health \
  -H "Authorization: Bearer $TOKEN"